ruby_decision_model 0.0.1 → 0.2.0

data/lib/ruby_decision_model/providers/base.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyDecisionModel
+  module Providers
+    # A provider owns everything that differs between decision-model APIs:
+    # where requests go, how they are authenticated, which model is the
+    # default, which model names are aliases, how the request is encoded, and
+    # how the response is read back. Client keeps the public API and
+    # delegates these questions here.
+    #
+    # The defaults speak the System One wire format that Typesafe published
+    # with Jev: questions keyed by id, answers keyed by id. A provider whose
+    # API differs overrides request_body and normalize_response, translating
+    # to and from that shape, so Client only ever sees System One answers.
+    class Base
+      attr_reader :api_key
+
+      def initialize(api_key: nil, base_url: nil)
+        @api_key = api_key || ENV.fetch(env_var, nil)
+        @base_url = base_url
+      end
+
+      # Identifier used in error messages and by Client#provider.
+      def name
+        raise NotImplementedError
+      end
+
+      def env_var
+        raise NotImplementedError
+      end
+
+      def default_base_url
+        raise NotImplementedError
+      end
+
+      def endpoint_path
+        raise NotImplementedError
+      end
+
+      def default_model
+        raise NotImplementedError
+      end
+
+      # Map of alias => canonical model name for this provider.
+      def aliases
+        {}
+      end
+
+      # Whether this provider reports a per-request cost in usage.
+      def reports_cost?
+        false
+      end
+
+      # Read timeout in seconds when Client gets timeout: nil. The open
+      # timeout stays at Client::DEFAULT_OPEN_TIMEOUT.
+      def default_timeout
+        5
+      end
+
+      # Whether requests may carry images. Client refuses images: for a
+      # provider that says no, before anything goes over the wire.
+      def supports_images?
+        false
+      end
+
+      # Response header carrying the provider's request id, or nil.
+      # Typesafe's, which 0.1.0 read for every provider and System One
+      # servers that follow Typesafe send too. Vendors with their own header
+      # override it.
+      def request_id_header
+        "x-typesafe-request-id"
+      end
+
+      # Whether a request without an API key is meaningful. Self-hosted
+      # servers often run without auth.
+      def requires_api_key?
+        true
+      end
+
+      # Values from env files often carry stray whitespace.
+      def base_url
+        (@base_url || default_base_url).to_s.strip.chomp("/")
+      end
+
+      # The model is passed for providers that put it in the path.
+      def url(_model = nil)
+        "#{base_url}#{endpoint_path}"
+      end
+
+      def api_key?
+        !(api_key.nil? || api_key.to_s.strip.empty?)
+      end
+
+      # Raises ConfigurationError naming whatever is missing.
+      def validate!
+        return unless requires_api_key? && !api_key?
+
+        raise ConfigurationError, "api_key is required for #{name}: pass api_key: or set #{env_var}"
+      end
+
+      # True when validate! would pass. Used to pick a provider from the
+      # environment.
+      def configured?
+        validate!
+        true
+      rescue ConfigurationError
+        false
+      end
+
+      # Nil or blank means the provider default. Known aliases resolve to the
+      # provider's canonical name. Anything else passes through untouched.
+      def resolve_model(model)
+        return default_model if model.nil? || model.to_s.strip.empty?
+
+        aliases.fetch(model.to_s, model.to_s)
+      end
+
+      def headers
+        headers = {
+          "Content-Type" => "application/json",
+          "Accept" => "application/json",
+          "User-Agent" => "ruby_decision_model/#{VERSION}"
+        }
+        # Keys read from files often end in a newline, which Net::HTTP
+        # rejects in a header.
+        headers["Authorization"] = "Bearer #{api_key.to_s.strip}" if api_key?
+        headers
+      end
+
+      # Client passes images: only when the caller supplied some, so a
+      # subclass that does not take images can keep a three-keyword
+      # signature.
+      def request_body(model:, state:, questions:, images: nil)
+        body = { "model" => model, "state" => state, "questions" => questions }
+        body["images"] = images if images
+        JSON.generate(body)
+      end
+
+      # Turns a parsed success body into the System One shape Client reads:
+      # a Hash with "answers" keyed by question id, plus "id", "model", and
+      # "usage". `questions` is the Hash the caller asked, for providers that
+      # need it to map answers back. Noul answers that arrive without a
+      # probability split get one.
+      def normalize_response(parsed, questions:)
+        fill_noul_probabilities(parsed)
+      end
+
+      # The vendor's reason for a failed request, read from the error body,
+      # or nil. Appended to the ApiError message. Knows the shapes the
+      # supported APIs use:
+      #   {"error": {"message": ...}}      OpenAI, Perplexity, OpenRouter
+      #   {"errors": [{"message": ...}]}   Cloudflare
+      #   {"detail": [{"loc", "msg"}]}     Typesafe and other FastAPI servers
+      #   {"message": ...}                 Databricks REST
+      def error_message(body)
+        parsed = JSON.parse(body.to_s)
+        parsed.is_a?(Hash) ? vendor_text(error_text(parsed)) : nil
+      rescue JSON::ParserError, EncodingError
+        nil
+      end
+
+      def usage(parsed)
+        raw = parsed.is_a?(Hash) && parsed["usage"].is_a?(Hash) ? parsed["usage"] : {}
+
+        Response::Usage.new(
+          input_tokens: Integer(raw["input_tokens"], exception: false),
+          output_tokens: Integer(raw["output_tokens"], exception: false),
+          cost: reports_cost? ? Float(raw["cost"], exception: false) : nil
+        )
+      end
+
+      # Keeps the API key out of logs and error output.
+      def inspect
+        "#<#{self.class.name} name=#{name.inspect} base_url=#{base_url.inspect} api_key=#{api_key? ? '[REDACTED]' : 'nil'}>"
+      end
+
+      # Applies non-nil overrides in place. Used when a caller hands Client a
+      # provider instance together with api_key: or base_url:.
+      def configure(api_key: nil, base_url: nil)
+        @api_key = api_key unless api_key.nil?
+        @base_url = base_url unless base_url.nil?
+        self
+      end
+
+      private
+
+      ERROR_MESSAGE_LIMIT = 500
+
+      def error_text(parsed)
+        error = parsed["error"]
+        return error if error.is_a?(String)
+        return error["message"].to_s if error.is_a?(Hash) && error["message"]
+
+        errors = parsed["errors"]
+        if errors.is_a?(Array) && errors.any?
+          return errors.map { |item| item.is_a?(Hash) ? item["message"] || item.to_s : item.to_s }.join("; ")
+        end
+
+        detail = parsed["detail"]
+        return detail if detail.is_a?(String)
+        return detail.map { |item| detail_text(item) }.join("; ") if detail.is_a?(Array) && detail.any?
+
+        (parsed["message"] || parsed["error_message"])&.to_s
+      end
+
+      def detail_text(item)
+        return item.to_s unless item.is_a?(Hash)
+
+        location = Array(item["loc"]).join(".")
+        location.empty? ? item["msg"].to_s : "#{location}: #{item['msg']}"
+      end
+
+      # Vendor-supplied text bound for an exception message, which tends to
+      # end up in logs: blank becomes nil, the API key is masked in case a
+      # vendor echoes it, and the length is capped.
+      def vendor_text(text)
+        # Net::HTTP hands back binary bodies; a proxy's error page can carry
+        # bytes that are not UTF-8, which strip and gsub would raise on.
+        text = text.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+        # Control characters could forge log lines or drive a terminal when
+        # the vendor echoes caller input; each run becomes one space.
+        text = text.gsub(/[[:cntrl:]]+/, " ").strip
+        return nil if text.empty?
+
+        key = api_key.to_s.strip
+        text = text.gsub(key, "[REDACTED]") if key.length >= 8
+        text.length > ERROR_MESSAGE_LIMIT ? "#{text[0, ERROR_MESSAGE_LIMIT]}..." : text
+      end
+
+      # Several APIs answer a noul with the probability alone. Fill in the
+      # two-way split Jev sends so Answers::Noul#probabilities reads the same
+      # everywhere.
+      def noul_probabilities(answer)
+        return answer unless answer.is_a?(Hash) && answer["type"] == "noul"
+        return answer if answer["probabilities"].is_a?(Hash) && !answer["probabilities"].empty?
+
+        probability = answer["noul"]
+        return answer unless probability.is_a?(Numeric)
+
+        answer.merge("probabilities" => { "true" => probability.to_f, "false" => 1.0 - probability.to_f })
+      end
+
+      def fill_noul_probabilities(parsed)
+        return parsed unless parsed.is_a?(Hash) && parsed["answers"].is_a?(Hash)
+
+        parsed.merge("answers" => parsed["answers"].transform_values { |answer| noul_probabilities(answer) })
+      end
+    end
+  end
+end

data/lib/ruby_decision_model/providers/cloudflare.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RubyDecisionModel
+  module Providers
+    # Cloudflare's Clef and Clef-flash on Workers AI. The body is System One
+    # with Cloudflare's images extension; the model also appears in the
+    # path, and the account id is required. Responses arrive inside the
+    # Workers AI envelope ({"result": ..., "success": true}), which is
+    # unwrapped here.
+    class Cloudflare < Base
+      ALIASES = {
+        "cloudflare/clef" => "clef",
+        "cloudflare/clef-flash" => "clef-flash",
+        "@cf/cloudflare/clef" => "clef",
+        "@cf/cloudflare/clef-flash" => "clef-flash"
+      }.freeze
+
+      # Cloudflare's own tooling reads CLOUDFLARE_API_TOKEN; the Clef docs
+      # use CLOUDFLARE_AUTH_TOKEN. Either works, in that order.
+      FALLBACK_ENV_VAR = "CLOUDFLARE_AUTH_TOKEN"
+      ACCOUNT_ENV_VAR = "CLOUDFLARE_ACCOUNT_ID"
+
+      # Both end up in the request path, so they are held to characters that
+      # cannot leave it.
+      ACCOUNT_ID_PATTERN = /\A[A-Za-z0-9_-]+\z/
+      MODEL_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9._-]*\z/
+
+      attr_reader :account_id
+
+      def initialize(api_key: nil, base_url: nil, account_id: nil)
+        # A blank CLOUDFLARE_API_TOKEN must not hide CLOUDFLARE_AUTH_TOKEN.
+        token = [env_var, FALLBACK_ENV_VAR].filter_map { |name| ENV.fetch(name, nil) }.find { |v| !v.strip.empty? }
+        super(api_key: api_key || token, base_url: base_url)
+        @account_id = (account_id || ENV.fetch(ACCOUNT_ENV_VAR, nil))&.to_s&.strip
+      end
+
+      def name
+        :cloudflare
+      end
+
+      def env_var
+        "CLOUDFLARE_API_TOKEN"
+      end
+
+      def default_base_url
+        "https://api.cloudflare.com/client/v4"
+      end
+
+      def endpoint_path
+        "/accounts/#{account_id}/ai/run/@cf/cloudflare"
+      end
+
+      # Checked here as well as at build time, since configure can change the
+      # account id on a provider a client already holds.
+      def url(model = nil)
+        model ||= default_model
+        unless account_id.to_s.match?(ACCOUNT_ID_PATTERN) && model.to_s.match?(MODEL_PATTERN)
+          raise ConfigurationError,
+                "cloudflare account_id and model must stay inside the URL path, got #{account_id.inspect} and #{model.inspect}"
+        end
+
+        "#{base_url}#{endpoint_path}/#{model}"
+      end
+
+      def default_model
+        "clef"
+      end
+
+      def aliases
+        ALIASES
+      end
+
+      def supports_images?
+        true
+      end
+
+      def request_id_header
+        "cf-ray"
+      end
+
+      def validate!
+        super
+        if account_id.nil? || account_id.to_s.strip.empty?
+          raise ConfigurationError, "account_id is required for cloudflare: pass account_id: or set #{ACCOUNT_ENV_VAR}"
+        end
+        return if account_id.to_s.match?(ACCOUNT_ID_PATTERN)
+
+        raise ConfigurationError, "cloudflare account_id must be letters, digits, - or _, got #{account_id.inspect}"
+      end
+
+      def resolve_model(model)
+        resolved = super
+        return resolved if resolved.match?(MODEL_PATTERN)
+
+        raise ConfigurationError, "cloudflare model must be a bare Workers AI name such as clef, got #{model.inspect}"
+      end
+
+      # Unwraps the Workers AI envelope. A body that says success: false
+      # carries no answers, so its errors become the exception message.
+      def normalize_response(parsed, questions:)
+        if parsed["success"] == false
+          detail = vendor_text(error_text(parsed))
+          raise InvalidResponse, ["cloudflare reported failure", detail].compact.join(": ")
+        end
+
+        body = parsed["result"].is_a?(Hash) ? parsed["result"] : parsed
+        super(body, questions: questions)
+      end
+
+      def configure(api_key: nil, base_url: nil, account_id: nil)
+        super(api_key: api_key, base_url: base_url)
+        @account_id = account_id.to_s.strip unless account_id.nil?
+        self
+      end
+    end
+  end
+end

data/lib/ruby_decision_model/providers/databricks.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RubyDecisionModel
+  module Providers
+    # Databricks ai_decide over REST (beta). Questions are System One, but
+    # the workspace serves one managed model, so the body has no model and
+    # Client#model is nil. Answers arrive under "response", and a noul
+    # carries "probability" where System One says "noul". Usage and ids are
+    # not reported.
+    class Databricks < Base
+      HOST_ENV_VAR = "DATABRICKS_HOST"
+
+      def initialize(api_key: nil, base_url: nil)
+        super
+        @base_url ||= ENV.fetch(HOST_ENV_VAR, nil)
+      end
+
+      def name
+        :databricks
+      end
+
+      def env_var
+        "DATABRICKS_TOKEN"
+      end
+
+      def default_base_url
+        nil
+      end
+
+      # DATABRICKS_HOST is often set without a scheme.
+      def base_url
+        host = super
+        return host if host.empty? || host.match?(%r{\Ahttps?://})
+
+        "https://#{host}"
+      end
+
+      # Beta serverless endpoint with no published latency figures.
+      def default_timeout
+        30
+      end
+
+      def endpoint_path
+        "/api/2.0/ai-functions/ai-decide"
+      end
+
+      def default_model
+        nil
+      end
+
+      def resolve_model(model)
+        return nil if model.nil? || model.to_s.strip.empty?
+
+        raise ConfigurationError, "databricks serves ai_decide's managed model and takes no model: (got #{model.inspect})"
+      end
+
+      def validate!
+        super
+        return unless base_url.empty?
+
+        raise ConfigurationError, "base_url is required for databricks: pass base_url: or set #{HOST_ENV_VAR}"
+      end
+
+      def request_body(model:, state:, questions:)
+        JSON.generate("state" => state, "questions" => questions)
+      end
+
+      def normalize_response(parsed, questions:)
+        if parsed["response"].nil? && parsed["error_message"]
+          raise InvalidResponse, "databricks ai_decide error: #{vendor_text(parsed['error_message'])}"
+        end
+
+        response = parsed["response"].is_a?(Hash) ? parsed["response"] : {}
+        answers = response["answers"].is_a?(Hash) ? response["answers"] : {}
+        answers = answers.transform_values do |answer|
+          next answer unless answer.is_a?(Hash) && answer["type"] == "noul" && !answer.key?("noul")
+
+          answer.merge("noul" => answer["probability"])
+        end
+
+        super({ "answers" => answers }, questions: questions)
+      end
+    end
+  end
+end

data/lib/ruby_decision_model/providers/open_router.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module RubyDecisionModel
+  module Providers
+    class OpenRouter < Base
+      # Short names resolve to the decision models OpenRouter routes, so the
+      # same model: works here and on each vendor's own provider.
+      ALIASES = {
+        "jev" => "typesafe/jev-1.13",
+        "jev-latest" => "typesafe/jev-1.13",
+        "luna" => "openai/gpt-6-luna-decisions",
+        "gpt-6-luna" => "openai/gpt-6-luna-decisions",
+        "clef" => "cloudflare/clef",
+        "clef-flash" => "cloudflare/clef-flash",
+        "pplx-decider" => "perplexity/pplx-decider-v1-27b",
+        "pplx-decider-v1-27b" => "perplexity/pplx-decider-v1-27b"
+      }.freeze
+
+      def name
+        :open_router
+      end
+
+      def env_var
+        "OPENROUTER_API_KEY"
+      end
+
+      def default_base_url
+        "https://openrouter.ai/api/alpha"
+      end
+
+      def endpoint_path
+        "/decisions"
+      end
+
+      def default_model
+        "typesafe/jev-1.13"
+      end
+
+      def aliases
+        ALIASES
+      end
+
+      def reports_cost?
+        true
+      end
+    end
+  end
+end