judge_rails 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1164267a3bd68794b33111be3918b6149bcd0f2f0b23755359eb8b79e677bece
-  data.tar.gz: 0b3dd424c618db92f4f1b82e216b1f9f894eabcf59a22e97c7570503ff4d46a9
+  metadata.gz: 4cd6199504db2095cd4dfc279ad386bd9effb10d5ab40719c8fe9cd8f0850822
+  data.tar.gz: 185fe243d146c57ee4d30c724b7104fe0f4624572467701ea25089a554508e27
 SHA512:
-  metadata.gz: c7f8955174b2a7983e47b171c5e601f3071c5bd5aa314c1ce2f42f936871f9b0c16669e542c7789faeca089f52a0345e1f3205ad8960ed2d35c81310605350ef
-  data.tar.gz: 5376194fbc848b03cac396fdac770d02c849acf0802fcbae9a8cecae716b2e43f7ea12427cc3d300ede0295f6f03aff531612a02accfd9ecd805990508f80e3f
+  metadata.gz: 0640bbb3751542608ff2d22863af16e5a1132d7b9247a2595149d82b30631ea6bc09e6e89ea75858eebdb25cbf6fdeb1cf8636a7d606bf0c6baace00588c9be9
+  data.tar.gz: fd33919299343282420c12f643651b8215ed3ee0135d0fb027dfb89dc5bfef8dedcbcec9c30239671fc257f2b683d83b83064edecb9bb7408862403e01904124

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.0.3 (2026-10-04)
+
+### Added
+
+- **Cloudflare Clef.** A built-in `:clef` adapter sends the same questions to Clef and Clef-flash on
+  Workers AI. It reuses the Jev client, so retries, pooling, errors and instrumentation behave the same.
+  `JUDGE_ADAPTER=clef` with `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` is the whole setup.
+- `config.cloudflare_api_token` and `config.cloudflare_account_id`, read from those two variables and
+  kept apart from `api_key`, so Jev and Clef can live in one app. `inspect` hides the token.
+- `adapter:` on `Judge.ask` and the ActiveRecord helpers now also takes a registered name, such as
+  `adapter: :clef`, and not only an adapter object.
+
+### Changed
+
+- With no explicit `config.model` or `JEV_MODEL`, the model follows the adapter: `clef` under `:clef`,
+  `jev-latest` otherwise. Nothing changes for Jev users. Moving an attribute to Clef changes its model,
+  so its stored judgments go stale and are recomputed.
+
 ## 0.0.2 (2026-09-26)
 
 No change to the gem itself. The first release published by `release.yml` through RubyGems trusted

data/README.md

@@ -469,7 +469,7 @@ The event carries sizes and counts. It never carries the state or the key.
 ```ruby
 Judge.configure do |config|
   config.api_key      = "..."                # read from JEV_API_KEY or TYPESAFE_API_KEY by default
-  config.model        = "jev-latest"
+  config.model        = "jev-latest"         # "clef" when the adapter is :clef
   config.timeout      = 10.0
   config.open_timeout = 5.0
   config.max_retries  = 2
@@ -543,6 +543,45 @@ The default is `:jev` and stays `:jev` until you change it. `JUDGE_ADAPTER` pick
 environment, and `adapter:` overrides it for a single call, which is how the test suite installs a
 recorder.
 
+### Cloudflare Clef
+
+`:clef` ships with the gem. It sends the same questions to [Clef](https://developers.cloudflare.com/workers-ai/models/clef/)
+on Cloudflare Workers AI and needs a Workers AI API token and your account id:
+
+```sh
+JUDGE_ADAPTER=clef
+CLOUDFLARE_API_TOKEN=...
+CLOUDFLARE_ACCOUNT_ID=...
+```
+
+```ruby
+Judge.configure do |config|
+  config.adapter               = :clef           # or JUDGE_ADAPTER=clef
+  config.cloudflare_api_token  = "..."           # read from CLOUDFLARE_API_TOKEN by default
+  config.cloudflare_account_id = "..."           # read from CLOUDFLARE_ACCOUNT_ID by default
+end
+
+Judge.ask(Judge.noul("Is this urgent?"), text: "Checkout is down for everyone").probability  # => 0.98
+```
+
+The model follows the adapter: `clef` under `:clef`, `jev-latest` otherwise. `clef-flash` is the smaller,
+faster one. Set it with `config.model`, `JEV_MODEL`, or a pin on one attribute:
+
+```ruby
+judge_attribute :urgency, Judge.noul("..."), model: "clef-flash"
+```
+
+Clef only serves those two names. Asking it for any other model raises `Judge::ConfigurationError` before
+a request leaves. `api_key` stays the Jev key, so one app can keep `:jev` and try Clef on a single call,
+naming the model since the configured one is still Jev's:
+
+```ruby
+Judge.ask(question, text: text, adapter: :clef, model: "clef")
+```
+
+Switching an attribute from Jev to Clef changes its model, so its stored judgments go stale and are
+recomputed on the next refresh, the same as changing a pin.
+
 ### You may not need an adapter at all
 
 The portable thing is the protocol, not this registry. Anything already serving this shape works

data/lib/generators/judge/templates/initializer.rb.tt

@@ -7,6 +7,13 @@ Judge.configure do |config|
 
   config.logger = Rails.logger
 
+  # Cloudflare Clef instead of Jev: set JUDGE_ADAPTER=clef, CLOUDFLARE_API_TOKEN and
+  # CLOUDFLARE_ACCOUNT_ID, or:
+  #
+  # config.adapter               = :clef
+  # config.cloudflare_api_token  = Rails.application.credentials.dig(:cloudflare, :api_token)
+  # config.cloudflare_account_id = Rails.application.credentials.dig(:cloudflare, :account_id)
+
   # Defaults, uncomment to override:
   #
   # config.base_url     = "https://api.typesafe.ai/v1/systemone"

data/lib/judge/adapter.rb

@@ -8,7 +8,7 @@ module Judge
 
     class << self
       def registry
-        @registry ||= { jev: -> { Client.new } }
+        @registry ||= { jev: -> { Client.new }, clef: -> { Clef.new } }
       end
 
       def register(name, &build)

data/lib/judge/clef.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "judge/client"
+
+module Judge
+  # Cloudflare's Clef on Workers AI. Same request and answers as Jev, behind a Cloudflare envelope
+  # and an account-scoped URL.
+  class Clef < Client
+    MODELS = %w[clef clef-flash].freeze
+    API_ROOT = "https://api.cloudflare.com/client/v4"
+
+    def initialize(config: nil, sleeper: nil, api_root: API_ROOT)
+      super(config: config, sleeper: sleeper)
+      @api_root = api_root.to_s.chomp("/")
+    end
+
+    def inspect
+      "#<Judge::Clef model=#{@config.model.inspect}>"
+    end
+
+    private
+
+    def endpoint(model)
+      unless MODELS.include?(model)
+        raise ConfigurationError, "Clef serves #{MODELS.join(" and ")}, not #{model.inspect}. " \
+                                  "Set config.model or pass model: \"clef\""
+      end
+
+      URI.parse("#{@api_root}/accounts/#{@config.cloudflare_account_id!}/ai/run/@cf/cloudflare/#{model}")
+    end
+
+    def authorization
+      "Bearer #{@config.cloudflare_api_token!}"
+    end
+
+    def unwrap(body)
+      result = body["result"]
+      return result if body["success"] != false && result.is_a?(Hash)
+
+      raise InvalidResponseError, "Cloudflare returned no result: #{error_message(JSON.generate(body))}"
+    end
+
+    def error_message(body)
+      parsed = JSON.parse(body)
+      errors = parsed["errors"] if parsed.is_a?(Hash)
+      message = errors.first["message"] if errors.is_a?(Array) && errors.first.is_a?(Hash)
+      message ? message.to_s : super
+    rescue JSON::ParserError
+      super
+    end
+  end
+end

data/lib/judge/client.rb

@@ -44,13 +44,14 @@ module Judge
       raise ArgumentError, "state must not be nil" if state.nil?
       raise ArgumentError, "questions must not be empty" if questions.nil? || questions.empty?
 
+      model ||= @config.model
+      target = endpoint(model)
       payload = JSON.generate(build_payload(state, questions, model))
-      event = { model: model || @config.model, questions: questions.size,
-                request_bytes: payload.bytesize }
+      event = { model: model, questions: questions.size, request_bytes: payload.bytesize }
 
       instrument(event) do
         started = monotonic
-        body = perform(payload)
+        body = unwrap(perform(target, payload))
         set = ResultSet.from_response(body, questions: questions, latency: monotonic - started)
         event[:latency] = set.latency
         event[:input_tokens] = set.usage&.input_tokens
@@ -70,18 +71,33 @@ module Judge
     def build_payload(state, questions, model)
       {
         "state" => state,
-        "model" => model || @config.model,
+        "model" => model,
         "questions" => questions.to_h { |name, question| [name.to_s, question.to_payload] }
       }
     end
 
-    def perform(payload)
-      authorization = "Bearer #{@config.api_key!}"
+    def endpoint(_model)
+      url = @config.base_url
+      @uri = URI.parse(url) if @uri_source != url
+      @uri_source = url
+      @uri
+    end
+
+    def authorization
+      "Bearer #{@config.api_key!}"
+    end
+
+    def unwrap(body)
+      body
+    end
+
+    def perform(target, payload)
+      authorization = self.authorization
       attempt = 0
 
       loop do
         attempt += 1
-        response = attempt_request(authorization, payload, attempt)
+        response = attempt_request(target, authorization, payload, attempt)
         next if response.nil?
 
         status = response.code.to_i
@@ -100,14 +116,14 @@ module Judge
       after || backoff(attempt)
     end
 
-    def attempt_request(authorization, payload, attempt)
+    def attempt_request(target, authorization, payload, attempt)
       started = monotonic
-      response = execute(authorization, payload)
-      log(response.code, monotonic - started, attempt)
+      response = execute(target, authorization, payload)
+      log(target, response.code, monotonic - started, attempt)
       response
     rescue *TRANSPORT_ERRORS => e
-      close_connection
-      log(e.class.name, monotonic - started, attempt)
+      close_connection(target)
+      log(target, e.class.name, monotonic - started, attempt)
       if attempt > @config.max_retries || UNSAFE_TO_RESEND.any? { |klass| e.is_a?(klass) }
         raise TransportError, "#{e.class}: #{e.message}"
       end
@@ -116,39 +132,31 @@ module Judge
       nil
     end
 
-    def execute(authorization, payload)
-      request = Net::HTTP::Post.new(uri.request_uri)
+    def execute(target, authorization, payload)
+      request = Net::HTTP::Post.new(target.request_uri)
       request["Authorization"] = authorization
       request["Content-Type"] = "application/json"
       request["Accept"] = "application/json"
       request.body = payload
-      connection.request(request)
-    end
-
-    def uri
-      url = @config.base_url
-      @uri = URI.parse(url) if @uri_source != url
-      @uri_source = url
-      @uri
+      connection(target).request(request)
     end
 
-    def connection_key
-      [@config.base_url, @config.open_timeout, @config.timeout].freeze
+    def connection_key(target)
+      [target.to_s, @config.open_timeout, @config.timeout].freeze
     end
 
-    def connection
+    def connection(target)
       store = connections
-      key = connection_key
+      key = connection_key(target)
       http = store[key]
       return http if http&.started?
 
-      store[key] = start_connection(key.first)
+      store[key] = start_connection(target)
     end
 
-    def start_connection(base_url)
-      uri = URI.parse(base_url)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
+    def start_connection(target)
+      http = Net::HTTP.new(target.host, target.port)
+      http.use_ssl = target.scheme == "https"
       http.open_timeout = @config.open_timeout
       http.read_timeout = @config.timeout
       http.write_timeout = @config.timeout if http.respond_to?(:write_timeout=)
@@ -166,8 +174,8 @@ module Judge
       store[:connections]
     end
 
-    def close_connection
-      http = connections.delete(connection_key)
+    def close_connection(target)
+      http = connections.delete(connection_key(target))
       http.finish if http&.started?
     rescue IOError
       nil
@@ -235,12 +243,12 @@ module Judge
       body.length > limit ? "#{body[0, limit]}..." : body
     end
 
-    def log(status, latency, attempt)
+    def log(target, status, latency, attempt)
       logger = @config.logger
       return unless logger
 
       logger.debug do
-        "Judge POST #{uri.path} status=#{status} latency=#{latency.round(3)}s attempt=#{attempt}"
+        "Judge POST #{target.path} status=#{status} latency=#{latency.round(3)}s attempt=#{attempt}"
       end
     end
 

data/lib/judge/configuration.rb

@@ -4,16 +4,19 @@ module Judge
   class Configuration
     DEFAULT_BASE_URL = "https://api.typesafe.ai/v1/systemone"
     DEFAULT_MODEL = "jev-latest"
+    CLEF_DEFAULT_MODEL = "clef"
 
-    attr_reader :api_key, :base_url, :model, :timeout, :open_timeout, :max_retries, :max_retry_wait,
-                :concurrency, :adapter
+    attr_reader :api_key, :base_url, :timeout, :open_timeout, :max_retries, :max_retry_wait,
+                :concurrency, :adapter, :cloudflare_api_token, :cloudflare_account_id
     attr_accessor :logger
 
     def initialize
       self.api_key = [ENV.fetch("JEV_API_KEY", nil), ENV.fetch("TYPESAFE_API_KEY", nil)]
                      .find { |value| !blank?(value) }
       self.base_url = present_env("JEV_BASE_URL") || DEFAULT_BASE_URL
-      self.model = present_env("JEV_MODEL") || DEFAULT_MODEL
+      @model = present_env("JEV_MODEL")
+      self.cloudflare_api_token = ENV.fetch("CLOUDFLARE_API_TOKEN", nil)
+      self.cloudflare_account_id = ENV.fetch("CLOUDFLARE_ACCOUNT_ID", nil)
       self.timeout = 10.0
       self.open_timeout = 5.0
       self.max_retries = 2
@@ -33,6 +36,18 @@ module Judge
       @base_url = value.to_s.strip
     end
 
+    def cloudflare_api_token=(value)
+      @cloudflare_api_token = blank?(value) ? nil : value.to_s.strip
+    end
+
+    def cloudflare_account_id=(value)
+      @cloudflare_account_id = blank?(value) ? nil : value.to_s.strip
+    end
+
+    def model
+      @model || (@adapter == :clef ? CLEF_DEFAULT_MODEL : DEFAULT_MODEL)
+    end
+
     def model=(value)
       raise ArgumentError, "model must not be blank" if blank?(value)
 
@@ -77,10 +92,25 @@ module Judge
       raise ConfigurationError, "No Judge API key. Set JEV_API_KEY or Judge.configure { |c| c.api_key = ... }"
     end
 
+    def cloudflare_api_token!
+      return @cloudflare_api_token if @cloudflare_api_token
+
+      raise ConfigurationError, "No Cloudflare API token. Set CLOUDFLARE_API_TOKEN or " \
+                                "Judge.configure { |c| c.cloudflare_api_token = ... }"
+    end
+
+    def cloudflare_account_id!
+      return @cloudflare_account_id if @cloudflare_account_id
+
+      raise ConfigurationError, "No Cloudflare account id. Set CLOUDFLARE_ACCOUNT_ID or " \
+                                "Judge.configure { |c| c.cloudflare_account_id = ... }"
+    end
+
     def inspect
       key = @api_key ? "[FILTERED]" : "nil"
-      "#<Judge::Configuration api_key=#{key} base_url=#{@base_url.inspect} model=#{@model.inspect} " \
-        "adapter=#{@adapter.inspect}>"
+      token = @cloudflare_api_token ? "[FILTERED]" : "nil"
+      "#<Judge::Configuration api_key=#{key} cloudflare_api_token=#{token} base_url=#{@base_url.inspect} " \
+        "model=#{model.inspect} adapter=#{@adapter.inspect}>"
     end
 
     private

data/lib/judge/facade.rb

@@ -21,7 +21,8 @@ module Judge
       normalized = normalize_questions(questions)
       raise ArgumentError, "ask needs at least one question" if normalized.empty?
 
-      results = (adapter || self.adapter).call(state: text, questions: normalized, model: model)
+      provider = adapter ? Adapter.build(adapter) : self.adapter
+      results = provider.call(state: text, questions: normalized, model: model)
       return results unless single
 
       name = normalized.keys.first

data/lib/judge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Judge
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/judge.rb

@@ -18,6 +18,7 @@ module Judge
   extend Facade
 
   autoload :Client, "judge/client"
+  autoload :Clef, "judge/clef"
 
   @config_lock = Mutex.new
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: judge_rails
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Hugo V
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-26 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -69,6 +69,7 @@ files:
 - lib/generators/judge/templates/migration.rb.tt
 - lib/judge.rb
 - lib/judge/adapter.rb
+- lib/judge/clef.rb
 - lib/judge/client.rb
 - lib/judge/configuration.rb
 - lib/judge/decision.rb