whitebox 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e220dba2b201dbefd83250e9c32280b7fa75e4ac2c96ee4b69504977a0b7788d
+  data.tar.gz: 39d5c7e514dc44ac58d2c81a0ee86bb068713945f8855893edc46007058efdea
+SHA512:
+  metadata.gz: 2a7cbd567d6e67ed5369ddbd795400770cac507d126d8d53413ffb184a5bc76349bb91045d3b754534dca91efb7653bb117c330f676985a36d70a69f73f71781
+  data.tar.gz: 583a95bb0182f3edb0cf20989ea7287d11717e5f12e5c1af4016a0ed1098c536f65fb7f337e0bd17ff6dc77f93bcc31574e8ec810821ebaf77c09222f02e17f1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WhiteBox (Spaceman Tech LLC)
+
+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,125 @@
+# WhiteBox Ruby SDK
+
+Official Ruby client for [WhiteBox](https://whiteboxhq.ai) -- AI Decision Observability.
+
+Run every AI classification through multiple models. Measure agreement. Ship with confidence or escalate to a human.
+
+## Install
+
+```
+gem install whitebox
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "whitebox"
+```
+
+## Quick Start
+
+```ruby
+require "whitebox"
+
+wb = Whitebox::Client.new(api_key: "wb_live_...")
+
+# Classify something
+result = wb.decide(
+  input: "dish soap, lemon scent, 750ml",
+  options: ["personal_care", "household_cleaning", "kitchen", "grocery"],
+  prompt: "Classify the product into one category"
+)
+
+puts result.value       # "household_cleaning"
+puts result.confidence  # 0.94
+puts result.verdict     # "ship"
+puts result.runs.size   # 7
+```
+
+## Fast Mode
+
+3 runs, 2 models, sub-second latency:
+
+```ruby
+result = wb.decide_fast(
+  input: "my card was charged twice",
+  options: ["billing", "fraud", "shipping", "general"]
+)
+```
+
+## Custom Models
+
+Pick which models vote on your decision:
+
+```ruby
+result = wb.decide(
+  input: "suspicious login from new device",
+  options: ["legitimate", "suspicious", "fraudulent"],
+  models: ["openai/gpt-4o", "anthropic/claude-sonnet-4", "mistralai/mistral-large"],
+  runs: 9
+)
+```
+
+## Bulk Decisions
+
+Submit up to 100 items at once:
+
+```ruby
+batch = wb.decide_bulk(
+  items: [
+    { input: "dish soap, lemon, 750ml" },
+    { input: "rose hand cream, 100ml" },
+    { input: "bamboo cutting board" },
+  ],
+  options: ["personal_care", "household_cleaning", "kitchen"],
+  webhook_url: "https://yourapp.com/webhooks/whitebox"
+)
+
+puts batch.id       # UUID
+puts batch.status   # "processing"
+puts batch.total    # 3
+
+# Poll for results
+loop do
+  b = wb.get_batch(batch.id)
+  break if b.complete?
+  sleep 2
+end
+
+results = wb.get_batch_results(batch.id)
+```
+
+## Human Review
+
+List and resolve escalated decisions:
+
+```ruby
+reviews = wb.list_reviews
+reviews.each do |r|
+  puts "#{r.input} -- confidence: #{r.confidence}"
+end
+
+wb.resolve_review(reviews.first.id, answer: "household_cleaning")
+```
+
+## Error Handling
+
+```ruby
+begin
+  wb.decide(input: "test", options: ["a", "b"])
+rescue Whitebox::AuthenticationError
+  puts "Bad API key"
+rescue Whitebox::InsufficientCreditsError
+  puts "Buy more credits"
+rescue Whitebox::RateLimitError => e
+  puts "Rate limited, retry in #{e.retry_after}s"
+rescue Whitebox::Error => e
+  puts "Error: #{e.message} (#{e.status_code})"
+end
+```
+
+## Links
+
+- Documentation: https://whiteboxhq.ai/api-docs
+- Dashboard: https://whiteboxhq.ai/dashboard
+- Supported models: https://whiteboxhq.ai/api/v1/models

data/lib/whitebox/client.rb

@@ -0,0 +1,155 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Whitebox
+  class Client
+    BASE_URL = "https://whiteboxhq.ai/api/v1"
+
+    def initialize(api_key:, base_url: nil, timeout: 30)
+      @api_key = api_key
+      @base_url = base_url || BASE_URL
+      @timeout = timeout
+    end
+
+    # Single decision
+    def decide(input:, options:, prompt: nil, runs: 7, threshold: 0.75, sync: true, mode: "standard", models: nil)
+      body = {
+        input: input,
+        options: options,
+        prompt: prompt,
+        runs: runs,
+        threshold: threshold,
+        sync: sync,
+        mode: mode,
+      }
+      body[:models] = models if models
+
+      data = request(:post, "/decide", body)
+      Decision.from_hash(data)
+    end
+
+    # Fast mode: 3 runs, 2 models, sync
+    def decide_fast(input:, options:, prompt: nil, threshold: 0.75)
+      decide(input: input, options: options, prompt: prompt, threshold: threshold, mode: "fast", sync: true)
+    end
+
+    # Bulk decisions
+    def decide_bulk(items:, prompt: nil, options: nil, runs: 7, threshold: 0.75, webhook_url: nil)
+      body = {
+        items: items,
+        prompt: prompt,
+        options: options,
+        runs: runs,
+        threshold: threshold,
+        webhook_url: webhook_url,
+      }.compact
+
+      data = request(:post, "/decide/bulk", body)
+      Batch.from_hash(data)
+    end
+
+    # Get a single decision
+    def get_decision(id)
+      data = request(:get, "/decisions/#{id}")
+      Decision.from_hash(data)
+    end
+
+    # List decisions
+    def list_decisions(page: 1, per_page: 20)
+      data = request(:get, "/decisions?page=#{page}&per_page=#{per_page}")
+      (data["decisions"] || []).map { |d| Decision.from_hash(d) }
+    end
+
+    # Get batch status
+    def get_batch(id)
+      data = request(:get, "/batches/#{id}")
+      Batch.from_hash(data)
+    end
+
+    # Get batch results
+    def get_batch_results(id)
+      request(:get, "/batches/#{id}/results")
+    end
+
+    # List pending reviews
+    def list_reviews
+      data = request(:get, "/reviews")
+      (data.is_a?(Array) ? data : []).map { |r| Review.from_hash(r) }
+    end
+
+    # Resolve a review
+    def resolve_review(id, answer:)
+      data = request(:patch, "/reviews/#{id}", { answer: answer })
+      Review.from_hash(data)
+    end
+
+    # List supported models
+    def models
+      request(:get, "/models")
+    end
+
+    private
+
+    def request(method, path, body = nil)
+      uri = URI("#{@base_url}#{path}")
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = @timeout
+      http.open_timeout = 10
+
+      req = case method
+            when :get    then Net::HTTP::Get.new(uri)
+            when :post   then Net::HTTP::Post.new(uri)
+            when :patch  then Net::HTTP::Patch.new(uri)
+            when :delete then Net::HTTP::Delete.new(uri)
+            end
+
+      req["Authorization"] = "Bearer #{@api_key}"
+      req["Content-Type"] = "application/json"
+      req["Accept"] = "application/json"
+
+      if body
+        req.body = JSON.generate(body)
+      end
+
+      response = http.request(req)
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      body = begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        { "error" => response.body }
+      end
+
+      case response.code.to_i
+      when 200..299
+        body
+      when 401
+        raise AuthenticationError.new(
+          body["message"] || "Unauthorized",
+          status_code: 401, response: body
+        )
+      when 402
+        raise InsufficientCreditsError.new(
+          body["error"] || "Insufficient credits",
+          status_code: 402, response: body
+        )
+      when 429
+        raise RateLimitError.new(
+          body["message"] || "Rate limited",
+          status_code: 429, response: body,
+          retry_after: response["Retry-After"]&.to_i
+        )
+      else
+        raise Error.new(
+          body["error"] || body["message"] || "Request failed (#{response.code})",
+          status_code: response.code.to_i, response: body
+        )
+      end
+    end
+  end
+end

data/lib/whitebox/errors.rb

@@ -0,0 +1,23 @@
+module Whitebox
+  class Error < StandardError
+    attr_reader :status_code, :response
+
+    def initialize(message, status_code: nil, response: nil)
+      super(message)
+      @status_code = status_code
+      @response = response
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class InsufficientCreditsError < Error; end
+
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/whitebox/models.rb

@@ -0,0 +1,67 @@
+module Whitebox
+  Run = Data.define(:model, :answer, :logprob, :latency_ms) do
+    def self.from_hash(h)
+      new(
+        model: h["model"],
+        answer: h["answer"],
+        logprob: h["logprob"],
+        latency_ms: h["latency_ms"]
+      )
+    end
+  end
+
+  Decision = Data.define(:id, :status, :value, :confidence, :verdict, :escalated, :runs, :latency_ms, :cost_usd, :created_at, :mode) do
+    def self.from_hash(h)
+      new(
+        id: h["id"],
+        status: h["status"],
+        value: h["value"],
+        confidence: h["confidence"],
+        verdict: h["verdict"],
+        escalated: h["escalated"],
+        runs: (h["runs"] || []).map { |r| Run.from_hash(r) },
+        latency_ms: h["latency_ms"],
+        cost_usd: h["cost_usd"],
+        created_at: h["created_at"],
+        mode: h["mode"]
+      )
+    end
+
+    def shipped? = verdict == "ship"
+    def escalated? = escalated == true
+  end
+
+  Batch = Data.define(:id, :status, :total, :completed, :failed, :progress, :webhook_url, :completed_at, :created_at) do
+    def self.from_hash(h)
+      new(
+        id: h["id"],
+        status: h["status"],
+        total: h["total"],
+        completed: h["completed"],
+        failed: h["failed"],
+        progress: h["progress"],
+        webhook_url: h["webhook_url"],
+        completed_at: h["completed_at"],
+        created_at: h["created_at"]
+      )
+    end
+
+    def complete? = status == "complete"
+  end
+
+  Review = Data.define(:id, :decision_id, :status, :input, :options, :model_votes, :confidence, :sla_deadline, :created_at) do
+    def self.from_hash(h)
+      new(
+        id: h["id"],
+        decision_id: h["decision_id"],
+        status: h["status"],
+        input: h["input"],
+        options: h["options"],
+        model_votes: h["model_votes"],
+        confidence: h["confidence"],
+        sla_deadline: h["sla_deadline"],
+        created_at: h["created_at"]
+      )
+    end
+  end
+end

data/lib/whitebox/version.rb

@@ -0,0 +1,3 @@
+module Whitebox
+  VERSION = "0.1.0"
+end

data/lib/whitebox.rb

@@ -0,0 +1,7 @@
+require_relative "whitebox/version"
+require_relative "whitebox/errors"
+require_relative "whitebox/models"
+require_relative "whitebox/client"
+
+module Whitebox
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: whitebox
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- WhiteBox
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-28 00:00:00.000000000 Z
+dependencies: []
+description: Run every AI classification through multiple models. Measure agreement.
+  Ship with confidence or escalate to a human.
+email:
+- hello@whiteboxhq.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/whitebox.rb
+- lib/whitebox/client.rb
+- lib/whitebox/errors.rb
+- lib/whitebox/models.rb
+- lib/whitebox/version.rb
+homepage: https://whiteboxhq.ai
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://whiteboxhq.ai
+  source_code_uri: https://github.com/ja-roque/whitebox
+  changelog_uri: https://github.com/ja-roque/whitebox/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: WhiteBox SDK - AI Decision Observability
+test_files: []