typesafe-jev 0.2.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7645167a374f6815e9a4ee6b96b56d54f611a3a08b274467f963dedd66e786ca
-  data.tar.gz: 0d66633fe64b5061b9f1bf7cb59fdf74f73d711c332bb34f7bbf0be1a042b85c
+  metadata.gz: 56d8b9176783b02dfd76aa0c59e960fc25d2b936e852cdfa79658578ac5e4e9e
+  data.tar.gz: d534502c6f03804f0f96ea4839dc24c8fe28724e285f1fac53dcabe2fe5f7f8f
 SHA512:
-  metadata.gz: 6de70dbd0412a10808feb2f79e1635462056a0c8069306b3fd063167b15ff0e6706f64fc22719e3cdd47f21a3fff4a70c64d368660eb1491c5abd5b4240e7baf
-  data.tar.gz: fd391b3ecd54101ea40a0923d618ee6e9a884ae54c3c9876d9e3ef5ed3f3a8741b81b7ae032ebe3cf9e109cdf96df468bd3741995c94a6d0b949266ed2711622
+  metadata.gz: 034e9bdc3ae16ef9783612d7eea2ee524a3b457cfb666ce1095c5c43224dc148d1ce9442cd65c7b4a1f6eb0e8d5b88dcf32d3dfe1b0fe5b5e7c5e74f0df5a5b1
+  data.tar.gz: 10fcd78136555393c85d8876a31ac9584f61ce4464b7818d7c537698426b381545a53a768c99e1313d62cc74e19183e590b0aa5f434ab61465a5d36a01aa98eb

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.1
+
+- Fix gemspec metadata: point `source_code_uri`/`changelog_uri` and author/email at the `dtheofr` GitHub account.
+
+## 0.4.0
+
+- Add `Typesafe::Jev`, a `Typesafe::Client` subclass with the model pinned to `jev-latest`: `Jev.new(api_key: nil).evaluate(...)` plus a one-shot `Typesafe::Jev.evaluate(state:, questions:, api_key: nil)`.
+
+## 0.3.0
+
+- Add `Typesafe::Client`: `initialize(api_key:, model:)` (key from argument or `TYPESAFE_API_KEY`, model defaults to `jev-latest`) and `evaluate(state:, questions:, model: nil)` posting to the System One endpoint. Returns the parsed JSON response; non-2xx responses raise the stdlib `Net::HTTP` error as-is.
+
 ## 0.2.0
 
 - Add question classes: `Typesafe::Noul`, `Typesafe::Choice`, `Typesafe::Score` with the abstract `Typesafe::Question` base. Frozen, immutable value objects that validate their inputs and serialize to the TypeSafe API shape via `#to_h`/`#to_json`.

data/lib/typesafe/client.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+
+require_relative "question"
+
+module Typesafe
+  # HTTP client for the TypeSafe System One evaluation endpoint.
+  #
+  #   client = Typesafe::Client.new(api_key: "sk-...", model: "jev-latest")
+  #   client.evaluate(
+  #     state: { ticket: { text: "My payouts failed" } },
+  #     questions: { refund_requested: Typesafe::Noul.new("Does the customer request a refund?") }
+  #   )
+  #
+  # The API key comes from the +TYPESAFE_API_KEY+ environment variable unless
+  # passed at initialization. The model defaults to +"jev-latest"+ and may be
+  # overridden per call.
+  class Client
+    DEFAULT_MODEL = "jev-latest"
+    API_ENDPOINT = "https://api.typesafe.ai/v1/systemone"
+
+    # @return [String] the API key sent as +Authorization: Bearer <key>+.
+    attr_reader :api_key
+
+    # @return [String] the default model used when +evaluate+ gets none.
+    attr_reader :model
+
+    # @param api_key [String, nil] the TypeSafe API key; falls back to the
+    #   +TYPESAFE_API_KEY+ environment variable.
+    # @param model [String, nil] the default model; defaults to "jev-latest".
+    # @raise [ArgumentError] if no usable API key is found or +model+ is
+    #   present but not a non-empty String.
+    def initialize(api_key: nil, model: nil)
+      @api_key = freeze_string(api_key || ENV.fetch("TYPESAFE_API_KEY") { nil },
+                               "api_key must be a non-empty String " \
+                               "(passed at initialization or set in the TYPESAFE_API_KEY environment variable)")
+      @model = freeze_string(model || DEFAULT_MODEL, "model must be a non-empty String")
+      freeze
+    end
+
+    # Evaluates a state against a map of questions and returns the raw JSON
+    # response as a Hash, e.g. +{"model"=>..., "answers"=>{...}, "usage"=>...}+.
+    #
+    # @param state [String, Object, Array] the content to evaluate; passed
+    #   through as-is.
+    # @param questions [Hash{String, Symbol => Question}] question ids mapped
+    #   to Question objects; answers come back under the same keys.
+    # @param model [String, nil] model for this call; falls back to the model
+    #   given at initialization.
+    # @return [Hash] the parsed response body.
+    # @raise [ArgumentError] if +questions+ is not a non-empty Hash of
+    #   String/Symbol keys to Question values, or +model+ is invalid.
+    # @raise [Net::HTTPClientException, Net::HTTPFatalError] on any non-2xx
+    #   HTTP response.
+    def evaluate(state:, questions:, model: nil)
+      model = model.nil? ? self.model : freeze_string(model, "model must be a non-empty String")
+      questions = validate_questions!(questions)
+
+      body = JSON.generate(
+        state: state,
+        model: model,
+        questions: questions.transform_values(&:to_h)
+      )
+
+      response = post(body)
+      response.value
+      JSON.parse(response.body)
+    end
+
+    private
+
+    def post(body)
+      uri = URI(API_ENDPOINT)
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{api_key}"
+      request["Content-Type"] = "application/json"
+      request.body = body
+
+      Net::HTTP.start(
+        uri.host, uri.port,
+        use_ssl: true,
+        open_timeout: 5, write_timeout: 10, read_timeout: 30
+      ) { |http| http.request(request) }
+    end
+
+    def validate_questions!(questions)
+      unless questions.is_a?(Hash) && !questions.empty?
+        raise ArgumentError, "questions must be a non-empty Hash mapping question ids to Question objects"
+      end
+
+      questions.each do |id, question|
+        unless (id.is_a?(String) && !id.strip.empty?) || (id.is_a?(Symbol) && !id.to_s.strip.empty?)
+          raise ArgumentError, "questions keys must be non-empty String or Symbol question ids, got #{id.inspect}"
+        end
+
+        unless question.is_a?(Question)
+          raise ArgumentError, "questions values must be Typesafe::Question objects, got #{question.inspect}"
+        end
+      end
+
+      questions
+    end
+
+    def freeze_string(value, error_message)
+      unless value.is_a?(String) && !value.strip.empty?
+        raise ArgumentError, error_message
+      end
+
+      value.dup.freeze
+    end
+  end
+end

data/lib/typesafe/jev.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "client"
+
+module Typesafe
+  # Convenience facade over {Client} for TypeSafe's flagship model, Jev.
+  #
+  # The model is pinned to "jev-latest"; for any other model, use
+  # {Typesafe::Client} directly.
+  #
+  #   Typesafe::Jev.evaluate(state: "My payouts failed", questions: { urgent: Typesafe::Noul.new("Is this urgent?") })
+  #
+  # or, reusing one client:
+  #
+  #   jev = Typesafe::Jev.new
+  #   jev.evaluate(state: state, questions: questions)
+  class Jev < Client
+    PINNED_MODEL = "jev-latest"
+
+    # @param api_key [String, nil] the TypeSafe API key; falls back to the
+    #   +TYPESAFE_API_KEY+ environment variable.
+    # @raise [ArgumentError] if no usable API key is found.
+    def initialize(api_key: nil)
+      super(api_key: api_key, model: PINNED_MODEL)
+    end
+
+    # Evaluates a state against a map of questions with the pinned model.
+    #
+    # @param state [String, Object, Array] the content to evaluate; passed
+    #   through as-is.
+    # @param questions [Hash{String, Symbol => Question}] question ids mapped
+    #   to Question objects; answers come back under the same keys.
+    # @param model [String, nil] must be nil or "jev-latest".
+    # @return [Hash] the parsed response body.
+    # @raise [ArgumentError] if +questions+ is invalid or +model+ is not the
+    #   pinned one.
+    # @raise [Net::HTTPClientException, Net::HTTPFatalError] on any non-2xx
+    #   HTTP response.
+    def evaluate(state:, questions:, model: nil)
+      if model && model != PINNED_MODEL
+        raise ArgumentError,
+              "Typesafe::Jev pins the model to \"jev-latest\"; use Typesafe::Client for other models"
+      end
+
+      super(state: state, questions: questions, model: model)
+    end
+
+    # One-shot evaluation using a client built from the environment (or the
+    # given API key). Equivalent to <tt>Jev.new(api_key:).evaluate(...)</tt>.
+    #
+    # @param state [String, Object, Array] the content to evaluate.
+    # @param questions [Hash{String, Symbol => Question}] question ids mapped
+    #   to Question objects.
+    # @param api_key [String, nil] the TypeSafe API key; falls back to the
+    #   +TYPESAFE_API_KEY+ environment variable.
+    # @return [Hash] the parsed response body.
+    def self.evaluate(state:, questions:, api_key: nil)
+      new(api_key: api_key).evaluate(state: state, questions: questions)
+    end
+  end
+end

data/lib/typesafe/version.rb

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

data/lib/typesafe.rb

@@ -7,6 +7,8 @@ require_relative "typesafe/question"
 require_relative "typesafe/noul"
 require_relative "typesafe/choice"
 require_relative "typesafe/score"
+require_relative "typesafe/client"
+require_relative "typesafe/jev"
 
 module Typesafe
 end

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: typesafe-jev
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.1
 platform: ruby
 authors:
-- dtheo
+- dtheofr
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -37,9 +37,23 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: Use Jev, TypeSafe's System One model, from Ruby or Rails.
 email:
-- dtheo@users.noreply.github.com
+- dtheofr@users.noreply.github.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -49,6 +63,8 @@ files:
 - README.md
 - lib/typesafe.rb
 - lib/typesafe/choice.rb
+- lib/typesafe/client.rb
+- lib/typesafe/jev.rb
 - lib/typesafe/noul.rb
 - lib/typesafe/question.rb
 - lib/typesafe/score.rb
@@ -58,8 +74,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://docs.typesafe.ai
-  source_code_uri: https://github.com/dtheo/typesafe-jev-ruby
-  changelog_uri: https://github.com/dtheo/typesafe-jev-ruby/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/dtheofr/typesafe-jev-ruby
+  changelog_uri: https://github.com/dtheofr/typesafe-jev-ruby/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib