arbiter-gem 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1390ac17a355433c6f9e2f9f7a47e6b9b8a8ce166c8c37b1389e1950eb1696a
-  data.tar.gz: 7ef97bb093b05948eeed2746e1d30fc3df630b6bd13eea53d2f163898003d4eb
+  metadata.gz: c96f3c93f0987c1c51c5a7d9cd4b11606e41669e34bd2b9c35cc14511ddbc394
+  data.tar.gz: cec5e2049ddcec4bb643742e013cdd8652b49c4f74d053a56c4e06641720462e
 SHA512:
-  metadata.gz: a0a0a9382852eb361ca410cfe5a8aa28db293b2a052d490a7e64da5c34338ff30b33bafa0d3efa8b0d30e2389c0be0ab545d7034f40e6cb55269f9032aa0f108
-  data.tar.gz: a52e0d340a0a267cb354c18dccf7a91c59e6b1eaefc861632317d48a7f24676db0a1cdee576d755cf2dae0a58398f91eeb3c0385fb77c5defbf7a8e8dd22eb95
+  metadata.gz: da81138d05eea4fee1fee34b9c30aff833d3083b9d63bd25bd69ce71152ca201056abc8ca2f15d7869de4fd4fac9c029f797f2fa804763b79d003eba30ce87aa
+  data.tar.gz: 220b705b197ea2521b37d572facff43e95938c3de8d1ad2480be5c29e07dea4191fb8fe1815fba14d64493afbb892687fc315f719266a9fed2136df18a5415c0

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 # 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.
+## 0.1.1 — 2026-10-12
+
+- Route calls without a key to the public ARBITER endpoint, with its published daily free allowance.
+- Send configured API keys using `X-API-Key`, matching the authenticated GRIP gateway.
+- Document all five methods, authorization at execution, and HTTP 402 handling.
+- Add RubyGems homepage, source, documentation, changelog and issues metadata.
+
+## 0.1.0 — 2026-10-12
+
+- Initial Ruby compare, embed, rank, decide and dispatch APIs.

data/README.md

@@ -1,109 +1,118 @@
-# ARBITER for Ruby
+# ARBITER GEM
 
-**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
+Deterministic ARBITER measurement in Ruby applications, using the remote ARBITER engine. No local ARBITER binary or model downloads.
 
 ```bash
 gem install arbiter-gem
 ```
 
-Gemfile:
-
-```ruby
-gem "arbiter-gem"
-```
+## Quickstart — 10 free comparisons per day
 
-## Use
+The public ARBITER endpoint advertises **10 successful measurements per day without a key**. That allowance is enforced by the service, not the gem. Free requests use `https://arbiter.grip.fyi/v1/compare`.
 
 ```ruby
 require "arbiter"
 
-result = Arbiter.compare(
+Arbiter.configure(api_key: nil, base_url: "https://arbiter.grip.fyi")
+results = Arbiter.rank(
   query: "Resolve a failed payment",
-  candidates: ["Retry", "Escalate", "Notify"],
-  top_k: 3
+  candidates: ["Retry the payment", "Escalate to billing", "Notify the customer"]
 )
-puts result # raw ARBITER JSON object
+results.each { |row| puts "#{row[:candidate]}: #{row[:score]}" }
 ```
 
-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.
+For a direct HTTP trial (no Ruby required):
 
-Embeddings:
-
-```ruby
-response = Arbiter.embed(texts: ["one", "two"])
+```bash
+curl -sS https://arbiter.grip.fyi/v1/compare \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"Resolve a failed payment","candidates":["Retry the payment","Escalate to billing","Notify the customer"]}'
 ```
 
-### The Last Conditional
+**Free-allowance verification:** This route and policy originate from ARBITER's published CLI offering; if the live gateway returns 401, 403 or 402, check its current status before advertising the free tier as operational. No API key is needed for the published free tier.
 
-```ruby
-permitted = ->(name, _action) { name != :retry || payment.retry_allowed? }
+## Funded API-key credits
 
-actions = {
-  retry:    { description: "Retry the payment", run: -> { retry_payment } },
-  escalate: { description: "Escalate to billing", run: -> { escalate_payment } },
-  notify:   { description: "Notify customer", run: -> { notify_customer } }
-}
+For paid usage, start at https://grip.fyi and request a GRIP-issued funded API key. **A self-service key issuance or credit-pack checkout URL has not been independently verified.** Do not assume purchasing has completed until credits and a key are issued.
 
-# Measurement only — never runs Ruby callables:
-choice = Arbiter.decide(intent: "Resolve the payment", actions: actions, permitted: permitted)
-puts choice[:action]
+The working GRIP owner-access transport uses this header:
 
-# Opt-in execution with permission revalidated immediately before invocation:
-# Arbiter.dispatch(intent: "Resolve the payment", actions: actions, permitted: permitted)
+```http
+X-API-Key: YOUR_GRIP_API_KEY
 ```
 
-**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>"
+export GRIP_API_KEY="<the-key-issued-for-GRIP-credits>"
 ```
 
-`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
+require "arbiter"
+Arbiter.configure(api_key: ENV.fetch("GRIP_API_KEY"), base_url: "https://api.grip.fyi")
+puts Arbiter.compare(query: "Route incident", candidates: ["Escalate", "Restart service"])
+```
+
+**Rate:** advertised metered x402 charge of **$0.001 USDC per compare/embed call**. Credit-pack denominations and checkout are not confirmed in public documentation. RubyGems credentials are unrelated to API keys. The gem never signs wallet payments or authorizes spending automatically.
+
+## API
+
+All methods belong to the `Arbiter` module. `Arbiter.compare` and `Arbiter.embed` return decoded JSON; normalized rankings are obtained using `rank`.
 
 ```ruby
-Arbiter.configure(
-  api_key: ENV.fetch("ARBITER_API_KEY"),
-  base_url: "https://api.grip.fyi"
-)
+Arbiter.compare(query: "Current intent", candidates: ["A", "B"], top_k: 2)
+Arbiter.embed(texts: ["A", "B"])
+Arbiter.rank(query: "Current intent", candidates: ["A", "B"], top_k: 2)
 ```
 
-Endpoints: `POST /v1/compare` with `query`, `candidates`, optional `top_k`; `POST /v1/embed` with `texts`.
+`embed` is typically used with funded API access; verify public availability before relying on it without a key.
+
+Actions require a `description` and callable `run`:
+
+```ruby
+actions = {
+  retry: { description: "Retry the payment", run: -> { :retried } },
+  escalate: { description: "Escalate to billing", run: -> { :escalated } },
+  notify: { description: "Notify the customer", run: -> { :notified } }
+}
+
+allowed = ->(name, _action) { name != :retry }
 
-### HTTP 402
+# Measures only; no action is executed:
+choice = Arbiter.decide(intent: "Resolve failed payment", actions: actions, permitted: allowed)
+puts choice[:action]
 
-The ARBITER service may request x402 payment. This client never signs wallet transactions or spends automatically:
+# Explicitly executes a permitted callable, checking permission again before execution:
+executed = Arbiter.dispatch(intent: "Resolve failed payment", actions: actions, permitted: allowed)
+puts executed[:value]
+```
+
+`decide` and `dispatch` require **at least two permitted actions**. The application owns authorization; ranking cannot override it. `dispatch` sends another comparison request; it does not execute the earlier decision object.
+
+## Error handling
 
 ```ruby
 begin
-  Arbiter.compare(query: "...", candidates: ["A", "B"])
+  Arbiter.compare(query: "Resolve failed payment", candidates: ["Retry", "Escalate"])
 rescue Arbiter::PaymentRequired => e
-  puts "HTTP #{e.status} — payment required"
-  # e.challenge contains payment-related response headers, if supplied
+  warn "HTTP #{e.status} — obtain credits or handle the x402 challenge explicitly"
 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.
+### Environment variables
 
-## Testing
+- `ARBITER_API_KEY` or `GRIP_API_KEY`: optional API key, sent as `X-API-Key`.
+- `ARBITER_BASE_URL`: optional override. Otherwise keyless calls use the public endpoint and authenticated calls use the GRIP API.
 
-```bash
-ruby -Ilib:test test/test_arbiter.rb
-```
+## Links
 
-## Publishing
+- Docs: https://arbiter-gem.grip.fyi
+- RubyGems: https://rubygems.org/gems/arbiter-gem
+- Source: https://github.com/ziolndr/arbiter-gem (requires public repository publication)
+- GRIP: https://grip.fyi
 
-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.
+## Tests
 
-## 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.
+```bash
+ruby -Ilib:test test/test_arbiter.rb
+```
 
 MIT © 2026 Actual General Intelligence, Inc.

data/lib/arbiter/client.rb

@@ -2,20 +2,30 @@
 require "json"
 require "net/http"
 require "uri"
+require "open3"
+require "tempfile"
 
 module Arbiter
   class Client
-    DEFAULT_BASE_URL = "https://api.grip.fyi".freeze
+    PAID_BASE_URL = "https://api.grip.fyi".freeze
+    PUBLIC_BASE_URL = "https://arbiter.grip.fyi".freeze
+    DEFAULT_BASE_URL = PAID_BASE_URL
     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),
+                   base_url: ENV["ARBITER_BASE_URL"],
                    open_timeout: 5, read_timeout: 30, transport: nil)
       @api_key = api_key
+      # Keyless compare uses the public ARBITER free-allowance route.
+      # Funded/owner API keys use the GRIP gateway.
+      base_url ||= (@api_key && !@api_key.empty? ? PAID_BASE_URL : PUBLIC_BASE_URL)
       @base_url = base_url.to_s.sub(%r{/+$}, "")
       @open_timeout = open_timeout
       @read_timeout = read_timeout
-      @transport = transport
+      unless transport.nil? || transport == :auto || transport == :net_http || transport == :curl || transport.respond_to?(:call)
+        raise InvalidInput, "transport must be :auto, :curl, :net_http, or a callable"
+      end
+      @transport = transport || :auto
       validate_url!
     end
 
@@ -62,10 +72,12 @@ module Arbiter
     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?
+      headers["X-API-Key"] = @api_key if @api_key && !@api_key.empty?
       body = JSON.generate(payload)
-      response = if @transport
+      response = if @transport.respond_to?(:call)
                    @transport.call(uri, headers, body)
+                 elsif @transport == :curl || (@transport == :auto && curl_available? && known_grip_host?(uri))
+                   curl_post(uri, headers, body)
                  else
                    http_post(uri, headers, body)
                  end
@@ -90,6 +102,67 @@ module Arbiter
       raise HTTPError.new(0, "ARBITER transport error (#{e.class})")
     end
 
+
+    # The hosted GRIP gateway has rejected some default language HTTP clients
+    # at Cloudflare's browser-signature layer. Prefer curl for GRIP hosts when
+    # installed; never expose the API key in process argv, files, or exception
+    # text. Caller-supplied endpoints continue to use Net::HTTP by default.
+    def known_grip_host?(uri)
+      uri.scheme == "https" && ["api.grip.fyi", "arbiter.grip.fyi"].include?(uri.host)
+    end
+
+    def curl_available?
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |part|
+        File.executable?(File.join(part, "curl"))
+      end
+    end
+
+    CurlResponse = Struct.new(:code, :body, :headers) do
+      def each_header(&block)
+        headers.each(&block)
+      end
+    end
+
+    def curl_post(uri, headers, body)
+      raise HTTPError.new(0, "curl not available") unless curl_available?
+      Tempfile.create("arbiter-curl-payload") do |payload_file|
+        Tempfile.create("arbiter-curl-headers") do |header_file|
+          Tempfile.create("arbiter-curl-output") do |output_file|
+            payload_file.write(body)
+            payload_file.flush
+            # X-API-Key is passed via STDIN, not command line arguments.
+            headers.each_value do |value|
+              raise InvalidInput, "header contains a line break" if value.match?(/[\r\n]/)
+            end
+            config = headers.map { |key, value| %(header = "#{curl_escape(key + ': ' + value)}") }.join("\n") + "\n"
+            args = ["curl", "--config", "-", "--silent", "--show-error",
+                    "--connect-timeout", @open_timeout.to_s,
+                    "--max-time", (@open_timeout + @read_timeout).to_s,
+                    "--request", "POST", "--url", uri.to_s,
+                    "--data-binary", "@#{payload_file.path}",
+                    "--dump-header", header_file.path,
+                    "--output", output_file.path,
+                    "--write-out", "%{http_code}"]
+            stdout, _stderr, status = Open3.capture3(*args, stdin_data: config)
+            raise HTTPError.new(0, "ARBITER transport error (curl)") unless status.success?
+            code = stdout.strip
+            raise InvalidResponse, "curl returned no HTTP status" unless code.match?(/\A[1-5][0-9]{2}\z/)
+            lines = header_file.read.split(/\r?\n/)
+            response_headers = lines.filter_map do |line|
+              next if line.start_with?("HTTP/") || !line.include?(":")
+              key, value = line.split(":", 2)
+              [key.downcase.strip, value.to_s.strip]
+            end.to_h
+            CurlResponse.new(code, output_file.read, response_headers)
+          end
+        end
+      end
+    end
+
+    def curl_escape(value)
+      value.to_s.gsub("\\", "\\\\").gsub('"', '\\"')
+    end
+
     def http_post(uri, headers, body)
       req = Net::HTTP::Post.new(uri)
       headers.each { |key, value| req[key] = value }

data/lib/arbiter/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: arbiter-gem
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Actual General Intelligence, Inc.
@@ -9,8 +9,9 @@ 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.
+description: Measure and rank candidate actions with the ARBITER API from Ruby. Includes
+  compare, embed, rank, decide and dispatch; MCP interoperability and x402 payment
+  challenges. No native engine.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -24,11 +25,15 @@ files:
 - lib/arbiter/flow.rb
 - lib/arbiter/ranking.rb
 - lib/arbiter/version.rb
-homepage: https://arbiter.grip.fyi
+homepage: https://arbiter-gem.grip.fyi
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://arbiter.grip.fyi
+  homepage_uri: https://arbiter-gem.grip.fyi
+  source_code_uri: https://github.com/ziolndr/arbiter-gem
+  documentation_uri: https://arbiter-gem.grip.fyi/#methods
+  changelog_uri: https://github.com/ziolndr/arbiter-gem/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ziolndr/arbiter-gem/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -45,5 +50,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: ARBITER deterministic measurement for Ruby decisions and control flow
+summary: Deterministic decision, ranking and action selection in Ruby; ARBITER API,
+  MCP and x402
 test_files: []