jev 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 781481c48138ea6ac1692f01dcc1f21b26bec770298bedc6cf90e0292d99832e
-  data.tar.gz: 0b2ac85a437a493d763df6185fc91a36bd2602791eff90f785259cc11b587aaf
+  metadata.gz: 8aae91833da46887245893c38c7352702ef1780820bab8cf0860ce07cb83a0a1
+  data.tar.gz: 60f83973fe00f6e5355d7f9933ae960eb4e34a0d4a70c6496a605d7367d3e9c3
 SHA512:
-  metadata.gz: c26d592b1c9f1306b422e4640b8a21c90bef15d4a54d71f9122328f6222db0f049b1f72deb8a650ab21ba141562d6e13f5eb7795390c566ea1197ca3a2c0aede
-  data.tar.gz: 425789aaddd0b63b83fc943cff698ef239980a6e333f67c970c6bb8270e788d2c9496b0387acdf71d2bcd68bf6763d3ca91c3865dea4bf4a25c36209ff4de985
+  metadata.gz: d2498f4e69f5fa99b1dcd30826c9d5a7eae36afb2a3567df67c0f15b6039d239be2c034601f8d21a6612a6f4f4dca9eabedcfa9e4fcb510c570d61ac1052015e
+  data.tar.gz: 93379eee809c5bacf64493097e9c046d51e4906820990d99c4fddd9de08e849684a1341b6ff252604064e56ee94609b1c1e8241d4e3112cec17d6c8da63d8dfc

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-09-20
+
+First release with a working client. 0.1.0 shipped an empty module.
+
+### Added
+
+- `Jev::Query` for building a batch of questions against a single state, with
+  `ask` (noul), `choose` (choice) and `score` (score).
+- `Jev::Question` and its three subclasses, sharing a uniform `result` for the
+  typed value to branch on, alongside type-specific accessors:
+  - `Noul` — `noul`, plus a per-question `threshold:` (default `0.5`).
+  - `Choice` — `choice`, `probabilities`, `confidence`. Up to 255 options.
+  - `Score` — `score`, `legend`, `probabilities`, `confidence`, plus `level` and
+    `label` for the most probable level. 2 to 10 levels.
+- `criteria:` on noul questions, `options:` on choice, `levels:` on score, all
+  serialised to the API's `criteria` field.
+- `Jev::Response` exposing the resolved `model` (e.g. `jev-1.13.0`, not
+  `jev-latest`), token `usage`, and `answers`.
+- `Jev::Collection`, an Enumerable set of answers supporting attribute access
+  (`answers.is_urgent`) and lookup by identifier (`answers[:is_urgent]`).
+- An error hierarchy under `Jev::Error`: `Jev::APIError` (carrying `status` and
+  `body`) with `AuthenticationError` (401), `ValidationError` (422),
+  `RateLimitError` (429) and `OverloadedError` (529).
+- `Jev.api_key` for global configuration, and `Jev::Client.new(api_key)` for
+  callers that need more than one key.
+
+### Notes
+
+- Rate limits are not retried. The API documentation recommends exponential
+  backoff on 429 and 529; this client raises `Jev::RateLimitError` and
+  `Jev::OverloadedError` so that policy stays with the caller.
+- Requests are sent as `jev-latest` and use `Net::HTTP`'s default timeouts.
+- Reading `result` on an unanswered question raises `Jev::Error` rather than
+  returning a falsy value.
+
+[0.2.0]: https://github.com/virolea/jev/releases/tag/v0.2.0

data/README.md

@@ -2,8 +2,6 @@
 
 A Ruby client for the [Typesafe](https://typesafe.ai) Jev model API.
 
-> Status: early skeleton — the client surface is not implemented yet.
-
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -18,9 +16,188 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install jev
 ```
 
-## Usage
+## Configuration
+
+Set your API key once, typically in an initializer:
+
+```ruby
+Jev.api_key = _YOUR_JEV_API_KEY_ 
+```
+
+## Quick start
+
+```ruby
+response = Jev::Query.new("Help! My payouts have been failing for 3 days.").perform do |query|
+  query.ask(:is_urgent, "Does this convey urgency?")
+end
+
+response.answers.is_urgent.result  # => true
+response.answers.is_urgent.noul    # => 0.95
+```
+
+## The three question types
+
+Every question in a single query is evaluated in parallel against the same state, so
+adding questions costs far less than making another call. Prefer several narrow questions
+over one broad one.
+
+### `ask` — noul
+
+Evaluates the truth of a statement, returning a probability between 0 and 1.
+
+```ruby
+query.ask(:is_urgent, "Does this convey urgency?",
+          criteria: {
+            "true" => "Explicitly time-sensitive",
+            "false" => "No urgency expressed"
+          })
+```
+
+`criteria` is optional, but it is how you scope a noul — worth providing whenever the
+statement could be read more than one way.
+
+### `choose` — choice
+
+Selects one option from a set. Up to 255 options.
+
+```ruby
+query.choose(:department, "Which team should handle this?",
+             options: {
+               "billing" => "Payments, invoicing, refunds",
+               "technical" => "Bugs, outages, integrations",
+               "sales" => "Pricing, upgrades, new accounts"
+             })
+```
+
+### `score` — score
+
+Rates the state against an ordered rubric of 2 to 10 levels.
+
+```ruby
+query.score(:frustration, "How frustrated is the customer?",
+            levels: ["Calm", "Frustrated", "Very angry"])
+```
+
+## Reading answers
+
+Every answer exposes `result` — the typed value to branch on — whatever its type:
+
+```ruby
+answers = response.answers
+
+answers.is_urgent.result    # => true       (noul, thresholded)
+answers.department.result   # => "billing"  (the chosen option)
+answers.frustration.result  # => 1.05       (the probability-weighted score)
+```
+
+Underneath that, each type exposes what the model actually returned:
+
+```ruby
+answers.is_urgent.noul             # => 0.95
+answers.department.probabilities   # => { "billing" => 0.88, "technical" => 0.12, "sales" => 0.0 }
+answers.department.confidence      # => 0.81
+answers.frustration.level          # => 1            (most probable level)
+answers.frustration.label          # => "Frustrated"  (that level, via the legend)
+answers.frustration.probabilities  # => { "0" => 0.0, "1" => 0.95, "2" => 0.05 }
+```
 
-TODO: Write usage instructions here
+Reading `result` on a question that has not been answered raises `Jev::Error` rather than
+returning a falsy value — so "the model said no" is never confused with "we never asked".
+
+Answers are enumerable, which is where combining atomic questions pays off:
+
+```ruby
+answers.map(&:identifier)                       # => [:is_urgent, :department, :frustration]
+answers.to_h { |a| [a.identifier, a.result] }   # => { is_urgent: true, department: "billing", frustration: 1.05 }
+answers[:department]                            # => the question, looked up by identifier
+answers.count                                   # => 3
+```
+
+Note that `result` is truthy for any answered choice or score, so `select(&:result)` only
+narrows a set of nouls.
+
+### Thresholds
+
+A noul's `result` is its probability compared against a threshold, which defaults to 0.5.
+The threshold belongs to the question, since the confidence you need is part of what you
+are asking:
+
+```ruby
+query.ask(:is_urgent, "Does this convey urgency?", threshold: 0.8)
+```
+
+The raw probability is always available via `noul` if you would rather route on it yourself.
+
+### Acting on a score
+
+A score answer gives you two different views, and which you want depends on what you are doing.
+
+**For a decision, use `level` or `label`.** These report the most probable level, which is
+what the model actually asserted:
+
+```ruby
+case answers.frustration.label
+when "Very angry" then escalate_to_human
+when "Frustrated" then flag_for_review
+else                   autorespond
+end
+```
+
+**For ranking or aggregation, use `result`**, the probability-weighted value. It is the only
+one of the two that gives a total order or a meaningful average:
+
+```ruby
+tickets.sort_by { |ticket| -ticket.answers.frustration.result }
+weekly_average = scores.sum(&:result) / scores.size
+```
+
+Be careful thresholding `result` directly. A rubric's levels are ordered but not evenly
+spaced, so a cutoff like `result >= 1.5` assumes a scale the rubric does not really have.
+It can also mislead on a split distribution: probabilities of
+`{ "0" => 0.5, "1" => 0.1, "2" => 0.4 }` average to `0.9`, pointing near *Frustrated*,
+the one level the model considers least likely. `level` reports `0` there, which is honest.
+Check `confidence` before acting on a weighted score.
+
+Ties in `level` resolve to the lower level.
+
+## Response metadata
+
+```ruby
+response.model              # => "jev-1.13.0"  — the version that actually answered
+response.usage.input_tokens  # => 318
+response.usage.output_tokens # => 34
+```
+
+Note that `model` is the *resolved* version. Requests are sent as `jev-latest`, so this is
+how you find out what you actually got.
+
+## Errors
+
+All errors inherit from `Jev::Error`:
+
+```ruby
+begin
+  query.perform
+rescue Jev::AuthenticationError  # 401
+rescue Jev::ValidationError      # 422
+rescue Jev::RateLimitError       # 429
+rescue Jev::OverloadedError      # 529
+rescue Jev::APIError => e        # any other non-success status
+  e.status  # => 500
+  e.body    # => the raw response body
+end
+```
+
+**Rate limits are not retried for you.** The API documentation recommends exponential
+backoff on 429 and 529; this client raises instead, so that policy stays yours:
+
+```ruby
+begin
+  query.perform
+rescue Jev::RateLimitError, Jev::OverloadedError
+  # back off and retry on your own terms
+end
+```
 
 ## Development
 

data/lib/jev/client.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Jev
+  class Client
+    API_URL = "https://api.typesafe.ai/v1/systemone"
+    MODEL = "jev-latest"
+
+    ERRORS_BY_STATUS = {
+      401 => AuthenticationError,
+      422 => ValidationError,
+      429 => RateLimitError,
+      529 => OverloadedError
+    }.freeze
+
+    def initialize(api_key)
+      raise ArgumentError, "Missing API key" unless api_key
+
+      @api_key = api_key
+    end
+
+    def request(state:, questions:)
+      body = { model: MODEL, state: state, questions: questions }
+
+      response = Net::HTTP.post(uri, body.to_json, request_headers)
+      raise error_for(response) unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body)
+    end
+
+    private
+
+    def error_for(response)
+      status = response.code.to_i
+
+      ERRORS_BY_STATUS.fetch(status, APIError).new(status, response.body)
+    end
+
+    def uri
+      URI(API_URL)
+    end
+
+    def request_headers
+      {
+        "Content-Type": "application/json",
+        "Authorization": "Bearer #{@api_key}"
+      }
+    end
+  end
+end

data/lib/jev/collection.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Jev
+  class Collection
+    include Enumerable
+
+    def initialize(questions)
+      @questions = questions
+      @questions.each do |question|
+        next if respond_to?(question.identifier)
+
+        define_singleton_method(question.identifier) { question }
+      end
+    end
+
+    def each(&) = @questions.each(&)
+
+    def [](identifier)
+      @questions.find { |question| question.identifier == identifier.to_sym }
+    end
+  end
+end

data/lib/jev/query.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Jev
+  class Query
+    def initialize(state)
+      @state = state
+      @questions = {}
+    end
+
+    def ask(identifier, content, **options)
+      add(Question::Noul, identifier, content, **options)
+    end
+
+    def choose(identifier, content, options:)
+      add(Question::Choice, identifier, content, options: options)
+    end
+
+    def score(identifier, content, levels:)
+      add(Question::Score, identifier, content, levels: levels)
+    end
+
+    def questions = Collection.new(@questions.values)
+
+    def perform
+      yield self if block_given?
+
+      payload = Jev.client.request(state: @state, questions: @questions.transform_values(&:to_h))
+      distribute_answers_across_questions(payload["answers"])
+
+      Response.new(payload, answers: questions)
+    end
+
+    private
+
+    def add(type, identifier, content, **options)
+      identifier = identifier.to_sym
+      raise ArgumentError, "#{identifier} has already been asked" if @questions.key?(identifier)
+
+      @questions[identifier] = type.new(identifier, content, **options)
+      self
+    end
+
+    def distribute_answers_across_questions(answers)
+      answers.each { |identifier, answer| @questions.fetch(identifier.to_sym).answer_with(answer) }
+    end
+  end
+end

data/lib/jev/question/choice.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Jev
+  class Question
+    class Choice < Question
+      MAX_OPTIONS = 255
+
+      attr_reader :choice, :probabilities, :confidence
+
+      def initialize(identifier, content, options:)
+        super(identifier, content)
+        @options = options.transform_keys(&:to_s)
+        validate_options!
+      end
+
+      def answer_with(answer)
+        @choice = answer["choice"]
+        @probabilities = answer["probabilities"]
+        @confidence = answer["confidence"]
+      end
+
+      def answered? = !@choice.nil?
+
+      private
+
+      def type = :choice
+
+      def value = @choice
+
+      def criteria = @options
+
+      def validate_options!
+        return if @options.size.between?(1, MAX_OPTIONS)
+
+        raise ArgumentError, "a choice question takes 1 to #{MAX_OPTIONS} options, got #{@options.size}"
+      end
+    end
+  end
+end

data/lib/jev/question/noul.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Jev
+  class Question
+    class Noul < Question
+      DEFAULT_THRESHOLD = 0.5
+
+      attr_reader :noul
+
+      def initialize(identifier, content, threshold: DEFAULT_THRESHOLD, criteria: nil)
+        super(identifier, content)
+        @threshold = threshold
+        @criteria = criteria&.transform_keys(&:to_s)
+      end
+
+      def answer_with(answer)
+        @noul = answer["noul"]
+      end
+
+      def answered? = !@noul.nil?
+
+      private
+
+      attr_reader :criteria
+
+      def type = :noul
+
+      def value = @noul > @threshold
+    end
+  end
+end

data/lib/jev/question/score.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Jev
+  class Question
+    class Score < Question
+      LEVELS = (2..10)
+
+      attr_reader :score, :legend, :probabilities, :confidence
+
+      def initialize(identifier, content, levels:)
+        super(identifier, content)
+        @levels = Array(levels)
+        validate_levels!
+      end
+
+      def answer_with(answer)
+        @score = answer["score"]
+        @legend = answer["legend"]
+        @probabilities = answer["probabilities"]
+        @confidence = answer["confidence"]
+      end
+
+      def answered? = !@score.nil?
+
+      def level
+        ensure_answered!
+
+        probabilities.max_by { |_, probability| probability }.first.to_i
+      end
+
+      def label = legend[level.to_s]
+
+      private
+
+      def type = :score
+
+      def value = @score
+
+      def criteria = @levels
+
+      def validate_levels!
+        return if LEVELS.cover?(@levels.size)
+
+        raise ArgumentError, "a score question takes #{LEVELS.min} to #{LEVELS.max} levels, got #{@levels.size}"
+      end
+    end
+  end
+end

data/lib/jev/question.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Jev
+  class Question
+    attr_reader :identifier
+
+    def initialize(identifier, content)
+      @identifier = identifier.to_sym
+      @content = content
+    end
+
+    def to_h = { type: type, instructions: @content, criteria: criteria }.compact
+
+    def answer_with(_answer)
+      raise NotImplementedError, "#{self.class} must implement #answer_with"
+    end
+
+    def answered?
+      raise NotImplementedError, "#{self.class} must implement #answered?"
+    end
+
+    def result
+      ensure_answered!
+
+      value
+    end
+
+    private
+
+    def ensure_answered!
+      raise Error, "#{@identifier} has not been answered" unless answered?
+    end
+
+    def criteria = nil
+  end
+end

data/lib/jev/response.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Jev
+  class Response
+    Usage = Struct.new(:input_tokens, :output_tokens)
+
+    attr_reader :model, :usage, :answers
+
+    def initialize(payload, answers:)
+      @model = payload["model"]
+      @usage = Usage.new(*(payload["usage"] || {}).values_at("input_tokens", "output_tokens"))
+      @answers = answers
+    end
+  end
+end

data/lib/jev/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jev
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/jev.rb

@@ -1,8 +1,36 @@
 # frozen_string_literal: true
 
+require "zeitwerk"
+require "net/http"
+require "json"
 require_relative "jev/version"
 
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
 module Jev
   class Error < StandardError; end
-  # Your code goes here...
+
+  class APIError < Error
+    attr_reader :status, :body
+
+    def initialize(status, body)
+      @status = status
+      @body = body
+      super("Jev API error #{status}: #{body}")
+    end
+  end
+
+  class AuthenticationError < APIError; end
+  class ValidationError < APIError; end
+  class RateLimitError < APIError; end
+  class OverloadedError < APIError; end
+
+  class << self
+    attr_accessor :api_key
+
+    def client
+      @client ||= Client.new(api_key)
+    end
+  end
 end

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: jev
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Vincent Rolea
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
 description: A Ruby client for the Jev model API from Typesafe (https://typesafe.ai).
 email:
 - 3525369+virolea@users.noreply.github.com
@@ -16,10 +30,19 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/jev.rb
+- lib/jev/client.rb
+- lib/jev/collection.rb
+- lib/jev/query.rb
+- lib/jev/question.rb
+- lib/jev/question/choice.rb
+- lib/jev/question/noul.rb
+- lib/jev/question/score.rb
+- lib/jev/response.rb
 - lib/jev/version.rb
 - sig/jev.rbs
 homepage: https://github.com/virolea/jev