arbiter-gem 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c1390ac17a355433c6f9e2f9f7a47e6b9b8a8ce166c8c37b1389e1950eb1696a
+  data.tar.gz: 7ef97bb093b05948eeed2746e1d30fc3df630b6bd13eea53d2f163898003d4eb
+SHA512:
+  metadata.gz: a0a0a9382852eb361ca410cfe5a8aa28db293b2a052d490a7e64da5c34338ff30b33bafa0d3efa8b0d30e2389c0be0ab545d7034f40e6cb55269f9032aa0f108
+  data.tar.gz: a52e0d340a0a267cb354c18dccf7a91c59e6b1eaefc861632317d48a7f24676db0a1cdee576d755cf2dae0a58398f91eeb3c0385fb77c5defbf7a8e8dd22eb95

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0 — 2026-10-11
+- Initial `arbiter-gem` Ruby client for compare and embed.
+- Finite candidate ranking, decision, and opt-in callable dispatch.
+- Explicit 402 error handling; never spends funds automatically.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Actual General Intelligence, Inc.
+
+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,109 @@
+# ARBITER for Ruby
+
+**Gem:** `arbiter-gem`  
+**Ruby module:** `Arbiter`  
+**Concept:** The Last Conditional — measure a finite permitted action field instead of extending contextual branching logic.
+
+Deterministic remote ARBITER measurement in ordinary Ruby applications. No native engine, CLI installation, model weights, or Regolith required.
+
+## Install
+
+```bash
+gem install arbiter-gem
+```
+
+Gemfile:
+
+```ruby
+gem "arbiter-gem"
+```
+
+## Use
+
+```ruby
+require "arbiter"
+
+result = Arbiter.compare(
+  query: "Resolve a failed payment",
+  candidates: ["Retry", "Escalate", "Notify"],
+  top_k: 3
+)
+puts result # raw ARBITER JSON object
+```
+
+The `compare` call returns the raw decoded API JSON object. To obtain a normalized ranking for documented formats, use `Arbiter.rank(...)`. Unknown response formats raise `Arbiter::InvalidResponse` rather than invent a winner.
+
+Embeddings:
+
+```ruby
+response = Arbiter.embed(texts: ["one", "two"])
+```
+
+### The Last Conditional
+
+```ruby
+permitted = ->(name, _action) { name != :retry || payment.retry_allowed? }
+
+actions = {
+  retry:    { description: "Retry the payment", run: -> { retry_payment } },
+  escalate: { description: "Escalate to billing", run: -> { escalate_payment } },
+  notify:   { description: "Notify customer", run: -> { notify_customer } }
+}
+
+# Measurement only — never runs Ruby callables:
+choice = Arbiter.decide(intent: "Resolve the payment", actions: actions, permitted: permitted)
+puts choice[:action]
+
+# Opt-in execution with permission revalidated immediately before invocation:
+# Arbiter.dispatch(intent: "Resolve the payment", actions: actions, permitted: permitted)
+```
+
+**Authority is external to measurement.** Filter prohibited actions first. Hard policy rules, authorization, cryptographic checks and transactional safety still belong to the application. `dispatch` never executes unknown actions returned by the API. Both the input field and the selected action are checked.
+
+## Configuration
+
+```bash
+export ARBITER_API_KEY="<credit-api-key>"
+```
+
+`GRIP_API_KEY` is also recognized. If the GRIP API uses a different header for credits, adjust the `Client` configuration before publishing; the currently implemented key header is `Authorization: Bearer` and has not been live-verified against the credit-pack gateway.
+
+```ruby
+Arbiter.configure(
+  api_key: ENV.fetch("ARBITER_API_KEY"),
+  base_url: "https://api.grip.fyi"
+)
+```
+
+Endpoints: `POST /v1/compare` with `query`, `candidates`, optional `top_k`; `POST /v1/embed` with `texts`.
+
+### HTTP 402
+
+The ARBITER service may request x402 payment. This client never signs wallet transactions or spends automatically:
+
+```ruby
+begin
+  Arbiter.compare(query: "...", candidates: ["A", "B"])
+rescue Arbiter::PaymentRequired => e
+  puts "HTTP #{e.status} — payment required"
+  # e.challenge contains payment-related response headers, if supplied
+end
+```
+
+Use funded API-key credits if supported by the deployment, or integrate a separately authorized wallet payment mechanism. RubyGems publication credentials **are unrelated** to API credits.
+
+## Testing
+
+```bash
+ruby -Ilib:test test/test_arbiter.rb
+```
+
+## Publishing
+
+Run `./PUBLISH.command` on a machine already authenticated to RubyGems. It performs tests, builds the gem, then calls `gem push` using the existing RubyGems credential store. It never copies, prints, or packages credentials. Two-factor authentication may still require an OTP.
+
+## Scope
+
+Version 0.1.0 is a release candidate tested against stubbed HTTP responses. Before public release, validate the live API response schema, credit-key header, and Gem name availability. No x402 wallet signer is bundled.
+
+MIT © 2026 Actual General Intelligence, Inc.

data/lib/arbiter/client.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+require "json"
+require "net/http"
+require "uri"
+
+module Arbiter
+  class Client
+    DEFAULT_BASE_URL = "https://api.grip.fyi".freeze
+    attr_reader :base_url
+
+    def initialize(api_key: ENV["ARBITER_API_KEY"] || ENV["GRIP_API_KEY"],
+                   base_url: ENV.fetch("ARBITER_BASE_URL", DEFAULT_BASE_URL),
+                   open_timeout: 5, read_timeout: 30, transport: nil)
+      @api_key = api_key
+      @base_url = base_url.to_s.sub(%r{/+$}, "")
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @transport = transport
+      validate_url!
+    end
+
+    def compare(query:, candidates:, top_k: nil)
+      unless query.is_a?(String) && !query.strip.empty?
+        raise InvalidInput, "query must be a nonempty String"
+      end
+      unless candidates.is_a?(Array) && candidates.length >= 2 &&
+             candidates.all? { |c| c.is_a?(String) && !c.strip.empty? }
+        raise InvalidInput, "candidates must be an Array of at least two nonempty Strings"
+      end
+      payload = { query: query, candidates: candidates }
+      unless top_k.nil?
+        unless top_k.is_a?(Integer) && top_k.between?(1, candidates.length)
+          raise InvalidInput, "top_k must be an Integer between 1 and candidate count"
+        end
+        payload[:top_k] = top_k
+      end
+      request("/v1/compare", payload)
+    end
+
+    def embed(texts:)
+      unless texts.is_a?(Array) && !texts.empty? &&
+             texts.all? { |t| t.is_a?(String) && !t.strip.empty? }
+        raise InvalidInput, "texts must be a nonempty Array of nonempty Strings"
+      end
+      request("/v1/embed", { texts: texts })
+    end
+
+    private
+
+    def validate_url!
+      uri = URI(@base_url)
+      ok = uri.scheme == "https" && uri.host && !uri.host.empty? &&
+           uri.userinfo.nil? && uri.query.nil? && uri.fragment.nil?
+      # Plain HTTP may be used only for loopback development/test endpoints.
+      ok ||= uri.scheme == "http" && ["localhost", "127.0.0.1", "::1"].include?(uri.host) &&
+             uri.userinfo.nil? && uri.query.nil? && uri.fragment.nil?
+      raise InvalidInput, "base_url requires HTTPS (or loopback HTTP)" unless ok
+    rescue URI::InvalidURIError
+      raise InvalidInput, "base_url is invalid"
+    end
+
+    def request(path, payload)
+      uri = URI("#{@base_url}#{path}")
+      headers = { "content-type" => "application/json", "accept" => "application/json" }
+      headers["authorization"] = "Bearer #{@api_key}" if @api_key && !@api_key.empty?
+      body = JSON.generate(payload)
+      response = if @transport
+                   @transport.call(uri, headers, body)
+                 else
+                   http_post(uri, headers, body)
+                 end
+      status = response.code.to_i
+      case status
+      when 200..299
+        parsed = parse_json(response.body)
+        raise InvalidResponse, "ARBITER response must contain a JSON object" unless parsed.is_a?(Hash)
+        parsed
+      when 402
+        # Do not auto-sign or spend funds. Preserve challenge for a caller-controlled payment flow.
+        challenge = response.each_header.to_h.select { |key, _| key.match?(/payment|x402/i) }
+        raise PaymentRequired.new("ARBITER returned HTTP 402; configure credits or handle the payment challenge", challenge: challenge)
+      when 401, 403
+        raise Unauthorized, "ARBITER authentication or permission failed (HTTP #{status})"
+      else
+        raise HTTPError.new(status, "ARBITER HTTP #{status}: #{safe_detail(response.body)}")
+      end
+    rescue JSON::ParserError
+      raise InvalidResponse, "ARBITER returned invalid JSON"
+    rescue Net::OpenTimeout, Net::ReadTimeout, SocketError, SystemCallError => e
+      raise HTTPError.new(0, "ARBITER transport error (#{e.class})")
+    end
+
+    def http_post(uri, headers, body)
+      req = Net::HTTP::Post.new(uri)
+      headers.each { |key, value| req[key] = value }
+      req.body = body
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                      open_timeout: @open_timeout, read_timeout: @read_timeout) do |http|
+        http.request(req)
+      end
+    end
+
+    def parse_json(body)
+      JSON.parse(body.to_s)
+    end
+
+    def safe_detail(body)
+      obj = JSON.parse(body.to_s)
+      return "request failed" unless obj.is_a?(Hash)
+      detail = obj["error"] || obj["message"] || "request failed"
+      detail.is_a?(String) ? detail[0, 250] : "request failed"
+    rescue JSON::ParserError
+      "request failed"
+    end
+  end
+end

data/lib/arbiter/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+module Arbiter
+  class Error < StandardError; end
+  class InvalidInput < Error; end
+  class InvalidResponse < Error; end
+  class Unauthorized < Error; end
+  class PaymentRequired < Error
+    attr_reader :status, :challenge
+    def initialize(message = "ARBITER payment required", challenge: {})
+      @status = 402
+      @challenge = challenge.freeze
+      super(message)
+    end
+  end
+  class HTTPError < Error
+    attr_reader :status
+    def initialize(status, message)
+      @status = status
+      super(message)
+    end
+  end
+  class ActionNotPermitted < Error; end
+end

data/lib/arbiter/flow.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+module Arbiter
+  module Flow
+    module_function
+
+    # The caller supplies only authorized actions. A separate recheck runs just
+    # before execution to catch changed permissions after measurement.
+    #
+    # actions: { retry: { description: 'Retry card', run: -> { ... } }, ... }
+    # permitted: optional ->(name, action) { ... } policy callback
+    def decide(intent:, actions:, client: Arbiter.client, permitted: nil)
+      approved = validate_actions(actions, permitted)
+      raise ActionNotPermitted, "at least two permitted actions required" if approved.length < 2
+      descriptions = approved.values.map { |action| action.fetch(:description) }
+      if descriptions.uniq.length != descriptions.length
+        raise InvalidInput, "action descriptions must be unique"
+      end
+      raw = client.compare(query: intent, candidates: descriptions, top_k: approved.length)
+      ranking = Ranking.extract(raw, descriptions)
+      raise InvalidResponse, "ARBITER did not return a ranked candidate" if ranking.empty?
+      id = approved.keys.fetch(ranking.first.fetch(:index))
+      { action: id, ranking: ranking, raw: raw, permitted_actions: approved.keys }
+    end
+
+    def dispatch(intent:, actions:, client: Arbiter.client, permitted: nil)
+      decision = decide(intent: intent, actions: actions, client: client, permitted: permitted)
+      name = decision.fetch(:action)
+      action = actions.fetch(name)
+      # Revalidation at execution boundary. The caller's policy remains authoritative.
+      if permitted && !permitted.call(name, action)
+        raise ActionNotPermitted, "selected action is no longer permitted"
+      end
+      result = action.fetch(:run).call
+      decision.merge(executed: true, value: result)
+    end
+
+    def validate_actions(actions, permitted)
+      raise InvalidInput, "actions must be a Hash" unless actions.is_a?(Hash) && !actions.empty?
+      unless permitted.nil? || permitted.respond_to?(:call)
+        raise InvalidInput, "permitted must be a callable"
+      end
+      approved = {}
+      actions.each do |name, action|
+        unless (name.is_a?(Symbol) || name.is_a?(String)) && action.is_a?(Hash) &&
+               action[:description].is_a?(String) && !action[:description].strip.empty? &&
+               action[:run].respond_to?(:call)
+          raise InvalidInput, "each action needs an id, description, and callable :run"
+        end
+        approved[name] = action if !permitted || permitted.call(name, action)
+      end
+      approved
+    end
+  end
+end

data/lib/arbiter/ranking.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+module Arbiter
+  # Normalizes only unambiguous score/ranking data. Unknown response formats raise.
+  # Raw compare() responses remain available without normalization.
+  module Ranking
+    module_function
+
+    def extract(response, candidates)
+      raise InvalidResponse, "response must be a Hash" unless response.is_a?(Hash)
+      raise InvalidInput, "candidate strings must be unique for ranking" unless candidates.uniq.length == candidates.length
+
+      # Some integrations wrap the API body in { "result" => {...} }.
+      body = response["result"].is_a?(Hash) ? response["result"] : response
+
+      ["results", "ranking", "ranked", "ranked_candidates", "matches"].each do |field|
+        next unless body[field].is_a?(Array)
+        ranking = from_items(body[field], candidates)
+        return ranking if ranking
+      end
+      if body["scores"].is_a?(Array) && body["scores"].length == candidates.length &&
+         body["scores"].all? { |score| numeric?(score) }
+        return candidates.each_with_index.map { |candidate, i| row(candidate, i, Float(body["scores"][i])) }
+                         .sort_by { |item| [-item[:score], item[:index]] }
+      end
+      raise InvalidResponse, "unrecognized ARBITER ranking response; inspect raw compare() result"
+    end
+
+    def from_items(items, candidates)
+      return nil if items.empty?
+      used = {}
+      rows = items.map do |item|
+        idx, score = case item
+                     when Hash
+                       index = item["index"] || item["candidate_index"]
+                       label = item["candidate"] || item["text"] || item["value"]
+                       index = candidates.index(label) if index.nil? && label.is_a?(String)
+                       [index, item["score"] || item["resonance"]]
+                     when String
+                       [candidates.index(item), nil]
+                     when Integer
+                       [item, nil]
+                     else
+                       return nil
+                     end
+        return nil unless idx.is_a?(Integer) && idx.between?(0, candidates.length - 1)
+        return nil if used[idx]
+        return nil unless score.nil? || numeric?(score)
+        used[idx] = true
+        row(candidates[idx], idx, score.nil? ? nil : Float(score))
+      end
+      # Prefer API order if it supplies ordered items; never re-sort returned rankings.
+      rows
+    end
+
+    def row(candidate, index, score)
+      { candidate: candidate, index: index, score: score }
+    end
+
+    def numeric?(value)
+      (value.is_a?(Numeric) || value.is_a?(String)) && Float(value).finite?
+    rescue ArgumentError, TypeError
+      false
+    end
+  end
+end

data/lib/arbiter/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module Arbiter
+  VERSION = "0.1.0"
+end

data/lib/arbiter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+require_relative "arbiter/version"
+require_relative "arbiter/errors"
+require_relative "arbiter/client"
+require_relative "arbiter/ranking"
+require_relative "arbiter/flow"
+
+module Arbiter
+  class << self
+    attr_writer :client
+
+    def client
+      @client ||= Client.new
+    end
+
+    def configure(**settings)
+      self.client = Client.new(**settings)
+    end
+
+    def compare(**args)
+      client.compare(**args)
+    end
+
+    def embed(**args)
+      client.embed(**args)
+    end
+
+    def rank(query:, candidates:, top_k: nil)
+      response = compare(query: query, candidates: candidates, top_k: top_k)
+      Ranking.extract(response, candidates)
+    end
+
+    def decide(**args)
+      Flow.decide(**args)
+    end
+
+    def dispatch(**args)
+      Flow.dispatch(**args)
+    end
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: arbiter-gem
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Actual General Intelligence, Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Ruby client for ARBITER compare and embed, plus explicit finite-action
+  dispatch. Remote measurement, no local engine or binary.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/arbiter.rb
+- lib/arbiter/client.rb
+- lib/arbiter/errors.rb
+- lib/arbiter/flow.rb
+- lib/arbiter/ranking.rb
+- lib/arbiter/version.rb
+homepage: https://arbiter.grip.fyi
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://arbiter.grip.fyi
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: ARBITER deterministic measurement for Ruby decisions and control flow
+test_files: []