turnkit 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73e85ee51e846b0d62828d964ad53b00fd0f6ce1e11d56611b47b45462d49d9f
-  data.tar.gz: f4c4591902e4a9a9fc4c2a50c6e768ad6a4191ac242418434ff5d8b22e99143b
+  metadata.gz: af637ae31bf82bcdaaf638f4adc5b8aca0273b61a87e79783f257c792c4d7f1d
+  data.tar.gz: b25b5adc0626e1eea3643aed4a71ae5829df105c9d6c6296739ad2b7913ade67
 SHA512:
-  metadata.gz: cd39ba14aa1e48ce133d8b4cffc76d63939494a90466cfd62a5b70cb612f76f2caf8a5ffafc371272f00644ff1842a9b96768fea0724788721c45c3d36163655
-  data.tar.gz: a77ae5606a43be2790b54cf2a6c8eb78225b5f8b41d0f7b166b8c67b6568a357e65d1ae8f690b446c55afde370aab33d1d3f21dad30a7aec493eb2eb6007224c
+  metadata.gz: 6318b5bdab01bb9c81668a817b91b60e314ef60d64608a7a8cc30a3ef5caeb931aa501231cde114538cd821d45dcf41aaee2f238fe6871f4f4f6cc22e553b70f
+  data.tar.gz: f2a801c4cb643e67078b71f18c9814ee38ca9353255b7ca6cbf0294f558a2688790b349daf0015ae48e6777ea6b03b237d089ee98cc77ac92aad1690f11ef0a5

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.10.0 - 2026-09-19
+
+- Add `Adapters::OpenRouterJev` for the non-chat Decisions alpha endpoint, reusing
+  evaluation receipts, budgets, and fenced accounting. Prefer reported provider
+  charges and preserve billable malformed responses without weakening typed answers.
+- Document OpenRouter shadow/assist integration and add an opt-in, synthetic
+  one-request smoke test with semantic checks and runtime receipt replay.
+
 ## 0.9.0 - 2026-09-19
 
 - Add `Turn#internal_evaluation` and a dependency-free Cloudflare Jev adapter for

data/README.md

@@ -19,7 +19,7 @@ The [live validation app](examples/interactive_validation/README.md) exercises
 these controls with Rails 8.1, PostgreSQL, Sidekiq, and actual Astra/xhigh requests.
 
 For non-generative judgments, use [structured evaluations](docs/structured-evaluations.md).
-Cloudflare Jev supports Noul, Choice, and Score through a separate typed API with
+Cloudflare and OpenRouter Jev support Noul, Choice, and Score through a separate typed API with
 durable receipts, usage/cost accounting, and output-audit integration—not chat messages.
 
 ## Installation

data/lib/turnkit/adapters/open_router_jev.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "timeout"
+
+module TurnKit
+  module Adapters
+    # Decisions transport only. Turn owns attempts, accounting, and recovery.
+    class OpenRouterJev
+      MODEL = "typesafe/jev-1.13"
+      ENDPOINT = "https://openrouter.ai/api/alpha/decisions"
+
+      def initialize(api_key:, billing_identity:)
+        raise ConfigError, "OpenRouter API key is required" if api_key.to_s.empty?
+        raise ConfigError, "OpenRouter billing identity is required" if billing_identity.to_s.empty?
+        @api_key, @billing_identity = api_key, billing_identity
+      end
+
+      def inspect = "#<#{self.class.name}>"
+      def identity = { "provider" => "openrouter", "endpoint" => ENDPOINT, "account" => @billing_identity, "schema" => 1 }
+      def cost_model(model:) = "openrouter/#{model}"
+
+      def validate!(model:, state:, questions:)
+        raise InputError, "unsupported OpenRouter evaluation model" unless model == MODEL
+        input = Evaluation.input!(state: state, questions: questions)
+        raise InputError, "OpenRouter state cannot be null" if input["state"].nil?
+        input["questions"].each_value do |question|
+          valid = !question["instructions"].nil?
+          criteria = question["criteria"]
+          if question["type"] == "noul" && question.key?("criteria")
+            valid &&= criteria.is_a?(Hash) && criteria.keys.sort == %w[false true] && criteria.values.none?(&:nil?)
+          elsif question["type"] == "score"
+            valid &&= criteria.none?(&:nil?)
+          end
+          raise InputError, "invalid OpenRouter question" unless valid
+        end
+        input
+      end
+
+      def evaluate(model:, state:, questions:, timeout:)
+        raise ArgumentError, "timeout must be positive and finite" unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
+        input = validate!(model: model, state: state, questions: questions)
+        uri = URI(ENDPOINT)
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Content-Type"] = "application/json"
+        request["Accept"] = "application/json"
+        request.body = JSON.generate(input.merge("model" => model))
+        response = Timeout.timeout(timeout) do
+          Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: timeout, read_timeout: timeout, write_timeout: timeout) do |http|
+            http.max_retries = 0
+            http.request(request)
+          end
+        end
+        code = response.code.to_i
+        begin
+          value = JSON.parse(response.body)
+        rescue JSON::ParserError
+          value = nil
+        end
+        observed = observed_usage(value)
+        returned_model = value["model"] if value.is_a?(Hash) && value["model"].is_a?(String)
+        unless code.between?(200, 299)
+          uncertain = code == 408 || code >= 500
+          raise EvaluationError.new(uncertain ? :uncertain : :unavailable,
+            retryable: uncertain || code == 429, retry_after: retry_delay(response["Retry-After"]),
+            http_status: code, usage: observed, model: returned_model)
+        end
+        unless value.is_a?(Hash) && valid_cost?(value["usage"])
+          raise EvaluationError.new(:malformed, usage: observed, model: returned_model)
+        end
+        # OpenRouter's envelope and optional charge are not part of Jev's closed
+        # answer schema. Never synthesize its optional confidence/distributions.
+        normalized = value.slice("model", "answers", "usage")
+        normalized["usage"] = value["usage"].slice("input_tokens", "output_tokens")
+        begin
+          result = Evaluation.result!(normalized, questions: input.fetch("questions"))
+        rescue EvaluationError
+          raise EvaluationError.new(:malformed, usage: observed, model: returned_model), cause: nil
+        end
+        EvaluationResult.new(model: result.model, answers: result.answers, usage: observed)
+      rescue Timeout::Error, IOError, SystemCallError, OpenSSL::SSL::SSLError, SocketError, Net::HTTPBadResponse, Net::ProtocolError
+        raise EvaluationError.new(:uncertain, retryable: true), cause: nil
+      end
+
+      private
+        def valid_cost?(usage)
+          return false unless usage.is_a?(Hash)
+          return true unless usage.key?("cost")
+          cost = usage["cost"]
+          cost.is_a?(Numeric) && cost.finite? && cost >= 0
+        end
+
+        def observed_usage(value)
+          usage = value["usage"] if value.is_a?(Hash)
+          return unless usage.is_a?(Hash)
+          tokens = Evaluation.usage(usage.slice("input_tokens", "output_tokens"))
+          cost = usage["cost"] if valid_cost?(usage)
+          return unless tokens || cost
+          Usage.new(input_tokens: tokens&.input_tokens, output_tokens: tokens&.output_tokens, cost: cost)
+        end
+
+        def retry_delay(value)
+          return unless value
+          return value.to_f if value.match?(/\A\d+(\.\d+)?\z/)
+          [Time.httpdate(value) - Clock.now, 0].max
+        rescue ArgumentError
+          nil
+        end
+    end
+  end
+end

data/lib/turnkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TurnKit
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/turnkit.rb

@@ -52,6 +52,7 @@ require_relative "turnkit/turn"
 require_relative "turnkit/usage"
 require_relative "turnkit/run"
 require_relative "turnkit/adapters/cloudflare_jev"
+require_relative "turnkit/adapters/open_router_jev"
 require_relative "turnkit/adapters/codex"
 require_relative "turnkit/adapters/ruby_llm"
 require_relative "turnkit/active_record_store"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Sam Couch
@@ -39,6 +39,7 @@ files:
 - lib/turnkit/active_record_store.rb
 - lib/turnkit/adapters/cloudflare_jev.rb
 - lib/turnkit/adapters/codex.rb
+- lib/turnkit/adapters/open_router_jev.rb
 - lib/turnkit/adapters/ruby_llm.rb
 - lib/turnkit/agent.rb
 - lib/turnkit/authorization.rb