jev-feels 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cb1c944edfc8044a07d64239c6452cf8717eee7a2878777b010ce06c7e328794
+  data.tar.gz: 4c4092c5de15890bb9897934dffe82c515a236e441444caf016e282d20046060
+SHA512:
+  metadata.gz: c01170a2578338e6d8359399873593357c7896a2fa536eca538edd82830925d597e0bf6a6b5ffddb2fce804e9c974be6fe9a7eb7b62109d4078987f53743de75
+  data.tar.gz: 41919c36db8eb4497f57acac8ee0c02bcca2f8cb5e7a5bf7b347dadda62253e80a7b5a20274f5db199ea5642e5eb98c82909ac8b9546920a336bc9e5c54d2e8e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maxim Veysgeym
+
+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,127 @@
+# jev-feels
+
+Semantic checks as ordinary Ruby conditions.
+
+```ruby
+# Gemfile
+gem "jev-feels"
+
+require "feels"
+
+Jev.configure do |config|
+  config.api_key = ENV.fetch("JEV_API_KEY")
+end
+
+Jev.define :urgent, "Requires immediate attention or action"
+
+email = <<~EMAIL
+  Our production server has stopped responding.
+  Customers cannot access their accounts.
+  Please investigate immediately.
+EMAIL
+
+if Jev.feels?(email, :urgent)
+  puts "URGENT"
+end
+```
+
+## String sugar
+
+`require "feels"` does not change `String`. Opt in with a refinement:
+
+```ruby
+using Jev::Feels
+
+email.feels?(:urgent)
+```
+
+Or, if you really want a global patch:
+
+```ruby
+require "feels/string"
+
+email.feels?(:urgent)
+```
+
+## Probability vs predicate
+
+```ruby
+email.feels(:urgent)
+# => 0.94
+
+email.feels?(:urgent)
+# => true
+```
+
+`feels` is the calibrated probability that the predicate holds (a Jev [Noul](https://docs.typesafe.ai/primitives/noul.md), `0.0..1.0`).
+`feels?` is `feels >= threshold`. The default threshold is `0.5`.
+
+```ruby
+email.feels?(:urgent, threshold: 0.8)
+```
+
+## Ad-hoc predicates
+
+A `String` predicate is used as-is and is **not** registered:
+
+```ruby
+email.feels?("sounds like the sender is about to cancel their subscription")
+```
+
+A `Symbol` must already have a definition or you get `Jev::UndefinedDefinition`.
+
+## Definitions
+
+```ruby
+Jev.define :urgent, "Requires immediate attention or action"
+Jev.define :spam, "Unsolicited or unwanted promotional content"
+Jev.define :angry, "Expresses anger or hostility"
+
+Jev.definition(:urgent)
+Jev.definitions
+```
+
+`define` replaces an existing name. `definitions` returns a frozen copy of the registry.
+
+## Configuration
+
+```ruby
+Jev.configure do |config|
+  config.api_key = ENV["JEV_API_KEY"]
+  config.base_url = "https://api.typesafe.ai"
+  config.timeout = 10
+  config.threshold = 0.5
+end
+```
+
+For tests, inject a transport and skip the network:
+
+```ruby
+Jev.configure do |config|
+  config.transport = ->(_payload) {
+    { "answers" => { "feels" => { "type" => "noul", "noul" => 0.9 } } }
+  }
+end
+```
+
+```ruby
+Jev.reset_configuration!
+Jev.reset_definitions!
+```
+
+## Errors
+
+All errors inherit from `Jev::Error`. HTTP failures are wrapped; the original exception is available as `cause`. API keys are redacted from messages.
+
+| Error | When |
+| --- | --- |
+| `Jev::ConfigurationError` | Missing API key |
+| `Jev::UndefinedDefinition` | Unknown symbol predicate |
+| `Jev::AuthenticationError` | HTTP 401 |
+| `Jev::RateLimitError` | HTTP 429 |
+| `Jev::InvalidResponseError` | Unparseable or shapeless body |
+| `Jev::RequestError` | Timeouts, network errors, other HTTP failures |
+
+## What this talks to
+
+[Jev](https://docs.typesafe.ai/introduction.md) / TypeSafe System One. `POST https://api.typesafe.ai/v1/systemone` with a Noul question. That is an implementation detail of `feels`; the public API is just `Jev.feels` / `Jev.feels?`.

data/context7.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "jev-feels",
+  "description": "Ruby-like semantic text predicates via Jev. Jev.feels?(:urgent) is an ordinary condition, not an SDK session.",
+  "excludeFolders": ["spec"]
+}

data/lib/feels/string.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "feels"
+
+class String
+  def feels(...)
+    Jev.feels(self, ...)
+  end
+
+  def feels?(...)
+    Jev.feels?(self, ...)
+  end
+end

data/lib/feels.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "jev"

data/lib/jev/client.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Jev
+  class Client
+    QUESTION_ID = "feels"
+    MODEL = "jev-latest"
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def probability(text, instructions)
+      extract_noul(transport.call(payload(text, instructions)))
+    end
+
+    private
+
+    def transport
+      @configuration.transport || Transport.new(@configuration)
+    end
+
+    def payload(text, instructions)
+      {
+        "model" => MODEL,
+        "state" => text,
+        "questions" => {
+          QUESTION_ID => {
+            "type" => "noul",
+            "instructions" => instructions
+          }
+        }
+      }
+    end
+
+    def extract_noul(body)
+      raise InvalidResponseError, "Jev response is not a JSON object" unless body.is_a?(Hash)
+
+      answers = body["answers"]
+      raise InvalidResponseError, "Jev response is missing answers" unless answers.is_a?(Hash)
+
+      answer = answers[QUESTION_ID]
+      raise InvalidResponseError, "Jev response is missing the feels answer" unless answer.is_a?(Hash)
+
+      noul = answer["noul"]
+      raise InvalidResponseError, "Jev response is missing a noul probability" unless noul.is_a?(Numeric)
+
+      noul = Float(noul)
+      raise InvalidResponseError, "Jev noul probability is not finite" unless noul.finite?
+
+      # ponytail: clamp out-of-range noul; raise if Jev starts returning uncalibrated values
+      noul.clamp(0.0, 1.0)
+    end
+  end
+end

data/lib/jev/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Jev
+  class Configuration
+    DEFAULT_BASE_URL = "https://api.typesafe.ai"
+    DEFAULT_TIMEOUT = 10.0
+    DEFAULT_THRESHOLD = 0.5
+
+    attr_accessor :api_key, :transport
+    attr_reader :base_url, :timeout, :threshold
+
+    def initialize
+      @api_key = nil
+      @base_url = DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @threshold = DEFAULT_THRESHOLD
+      @transport = nil
+    end
+
+    def base_url=(value)
+      raise ArgumentError, "base_url must be a non-empty String" unless value.is_a?(String) && !value.empty?
+
+      @base_url = value
+    end
+
+    def timeout=(value)
+      raise ArgumentError, "timeout must be a positive number" unless value.is_a?(Numeric) && value.to_f.positive?
+
+      @timeout = value.to_f
+    end
+
+    def threshold=(value)
+      @threshold = Jev.normalize_threshold(value)
+    end
+  end
+end

data/lib/jev/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Jev
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class UndefinedDefinition < Error; end
+  class RequestError < Error; end
+  class AuthenticationError < RequestError; end
+  class RateLimitError < RequestError; end
+  class InvalidResponseError < Error; end
+end

data/lib/jev/feels.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Jev
+  module Feels
+    refine String do
+      def feels(...)
+        Jev.feels(self, ...)
+      end
+
+      def feels?(...)
+        Jev.feels?(self, ...)
+      end
+    end
+  end
+end

data/lib/jev/registry.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Jev
+  class Registry
+    def initialize
+      @mutex = Mutex.new
+      @definitions = {}
+    end
+
+    def define(name, description)
+      key = name.to_sym
+      value = description.to_s.dup.freeze
+      @mutex.synchronize { @definitions[key] = value }
+      value
+    end
+
+    def fetch(name)
+      @mutex.synchronize { @definitions[name.to_sym] }
+    end
+
+    def all
+      @mutex.synchronize { @definitions.dup.freeze }
+    end
+
+    def reset!
+      @mutex.synchronize { @definitions.clear }
+    end
+  end
+end

data/lib/jev/transport.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module Jev
+  class Transport
+    PATH = "v1/systemone"
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def call(payload)
+      handle_response(post(payload))
+    rescue Error
+      raise
+    rescue Timeout::Error
+      raise RequestError, "Jev request timed out"
+    rescue SystemCallError, SocketError, IOError, OpenSSL::SSL::SSLError => e
+      raise RequestError, redact("Jev request failed: #{e.message}")
+    end
+
+    private
+
+    def post(payload)
+      uri = endpoint
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      apply_timeouts(http)
+      http.request(build_request(uri, payload))
+    end
+
+    def apply_timeouts(http)
+      timeout = @configuration.timeout
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+    end
+
+    def build_request(uri, payload)
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["Authorization"] = "Bearer #{api_key}"
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request["User-Agent"] = "jev-feels/#{VERSION}"
+      request.body = JSON.generate(payload)
+      request
+    end
+
+    def api_key
+      key = @configuration.api_key
+      raise ConfigurationError, "Jev API key is missing" if key.nil? || key.empty?
+
+      key
+    end
+
+    def endpoint
+      base = @configuration.base_url
+      base = "#{base}/" unless base.end_with?("/")
+      URI.join(base, PATH)
+    end
+
+    def handle_response(response)
+      code = response.code.to_i
+      raw = response.body.to_s
+      return parse_success(raw) if code == 200
+
+      raise_http_error(code, raw)
+    end
+
+    def parse_success(raw)
+      body = JSON.parse(raw)
+      raise InvalidResponseError, "Jev response is not a JSON object" unless body.is_a?(Hash)
+
+      body
+    rescue JSON::ParserError
+      raise InvalidResponseError, "Jev response is not valid JSON"
+    end
+
+    def raise_http_error(code, raw)
+      detail = error_detail(raw)
+      case code
+      when 401
+        raise AuthenticationError, "Jev authentication failed"
+      when 429
+        raise RateLimitError, join_detail("Jev rate limit exceeded", detail)
+      else
+        raise RequestError, join_detail("Jev request failed with HTTP #{code}", detail)
+      end
+    end
+
+    def error_detail(raw)
+      text = extract_error_message(raw)
+      return if text.nil? || text.empty?
+
+      redact(text)
+    end
+
+    def extract_error_message(raw)
+      parsed = JSON.parse(raw)
+      message = parsed.values_at("error", "message", "detail").compact.first
+      message = message["message"] if message.is_a?(Hash)
+      message.to_s
+    rescue JSON::ParserError
+      raw.strip[0, 200]
+    end
+
+    def join_detail(prefix, detail)
+      detail ? "#{prefix}: #{detail}" : prefix
+    end
+
+    def redact(text)
+      key = @configuration.api_key
+      return text.to_s if key.nil? || key.empty?
+
+      text.to_s.gsub(key, "[FILTERED]")
+    end
+  end
+end

data/lib/jev/version.rb

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

data/lib/jev-feels.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "feels"

data/lib/jev.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "jev/version"
+require_relative "jev/errors"
+require_relative "jev/configuration"
+require_relative "jev/registry"
+require_relative "jev/transport"
+require_relative "jev/client"
+require_relative "jev/feels"
+
+module Jev
+  class << self
+    attr_reader :configuration
+
+    def configure
+      yield configuration
+      configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def define(name, description)
+      registry.define(name, description)
+    end
+
+    def definition(name)
+      registry.fetch(name)
+    end
+
+    def definitions
+      registry.all
+    end
+
+    def reset_definitions!
+      registry.reset!
+    end
+
+    def feels(text, predicate)
+      Client.new(configuration).probability(coerce_text(text), resolve(predicate))
+    end
+
+    def feels?(text, predicate, threshold: configuration.threshold)
+      feels(text, predicate) >= normalize_threshold(threshold)
+    end
+
+    def normalize_threshold(value)
+      raise ArgumentError, "threshold must be a Float between 0.0 and 1.0" unless value.is_a?(Numeric)
+
+      value = Float(value)
+      unless value.finite? && value.between?(0.0, 1.0)
+        raise ArgumentError, "threshold must be a Float between 0.0 and 1.0"
+      end
+
+      value
+    end
+
+    private
+
+    attr_reader :registry
+
+    def coerce_text(text)
+      text = text.to_str if !text.is_a?(String) && text.respond_to?(:to_str)
+      raise ArgumentError, "text must be a String" unless text.is_a?(String)
+
+      text
+    end
+
+    def resolve(predicate)
+      case predicate
+      when Symbol
+        definition(predicate) ||
+          raise(UndefinedDefinition, "Undefined Jev definition: #{predicate.inspect}")
+      when String
+        predicate
+      else
+        raise ArgumentError, "predicate must be a Symbol or String"
+      end
+    end
+  end
+
+  reset_configuration!
+  @registry = Registry.new
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: jev-feels
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Maxim Veysgeym
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-20 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Tiny Ruby API for semantic text checks. Jev.feels?(:urgent) is an ordinary
+  condition, not an SDK session. Jev stays an implementation detail.
+email:
+- Qew7@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- context7.json
+- lib/feels.rb
+- lib/feels/string.rb
+- lib/jev-feels.rb
+- lib/jev.rb
+- lib/jev/client.rb
+- lib/jev/configuration.rb
+- lib/jev/errors.rb
+- lib/jev/feels.rb
+- lib/jev/registry.rb
+- lib/jev/transport.rb
+- lib/jev/version.rb
+homepage: https://github.com/Qew7/jev-feels
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Qew7/jev-feels
+  source_code_uri: https://github.com/Qew7/jev-feels
+  changelog_uri: https://github.com/Qew7/jev-feels/blob/main/README.md
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby-like semantic predicates via Jev
+test_files: []