jev-feels 0.2.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 125dde58282251c7692d030e90352e098cf1785bc38904cf6021098d073d2f8a
-  data.tar.gz: 6bdf7fb784623b94cde049148294a1513e59207ccde0fd683869bbb4cc639a6d
+  metadata.gz: bf19b7812e88098da8abdb24e2c951f11ed906bf8f0200be8d889cc9c7565d13
+  data.tar.gz: 836af8d2b70dbf6828f170a01b8d00e19ffadb4a56b5e8409c845bef1500cda4
 SHA512:
-  metadata.gz: 2b5a17cbde5d54178e39eed6600fdff431f5fdfa0515af09f79f4711eb19b67148a87e669a973755d2afa9546c2fcd5e6e14e15b29d1ddc4908834bc24ca4570
-  data.tar.gz: fb31b5c3f4fb3d90204cbfa815a5bf3aff537eb8611645f5099c79b775f1fd6d8f6427dc4ea603a8b7f670278aae61fe7b7e6e009e7136528fd75ab2149c0c82
+  metadata.gz: 17e714115b72dbbb3dc0a69881d135ddbb670238ce4eb6bd7221ee10db3ea6c12a4f0c7aab00c17cf78277352d3063499d9bfd507f4160e15f6aa7940716b053
+  data.tar.gz: 0c05ddcd181d7cfec1eaee0df0c2582e3f34431989cc3231014440657b67295cb2fac42b93eff61a2defbbfe567bb671924e5dfa86f1f6ab0b174a78187d7f3d

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 1.1.0
+
+### Added
+
+- `Jev.define` accepts `choices:` (`decide`) and `levels:` (`score`, Hash, low to high).
+- `Jev.decide`, `Jev.score`, `Jev.measure`, and `Jev.match`.
+- Typed results: `Jev::Result::Noul`, `Jev::Result::Choice`, `Jev::Result::Score`, `Jev::Result::Batch`.
+- Batch `Jev.measure(state) { |q| ... }` — one request, defined names only.
+- `at_least:` on `feels?` (true / false / nil) and `confidence:` on `decide` / `match`.
+- Native `case`/`in` on a batch via collapsed values.
+- `Jev::Model`: `feels` / `decide` / `score` bind a field; instance `feels?`, `decide`, `score`, `measure`, `match`.
+- Optional `require "feels/active_model"` and `validates_feeling`.
+- `Jev.stub`, `Jev.record`, and `Jev.replay`. Tapes omit API keys.
+- Opt-in String refinement / extension: `decide`, `score`, `measure`.
+
+### Changed
+
+- `feels` / `feels?` / `decide` / `score` collapse a typed `Jev.measure` result.
+- Yes/no `Jev.definition` / `Jev.definitions` still return the instruction string. `choices:` / `levels:` return `Jev::Definition`.
+
+## 1.0.0
+
+- Initial `Jev.define` / `Jev.feels` / `Jev.feels?` API, injectable transport, and opt-in String sugar.

data/README.md

@@ -1,12 +1,13 @@
 # jev-feels
 
-Semantic checks as ordinary Ruby conditions.
+Semantic decisions as ordinary Ruby.
 
 ```ruby
 # Gemfile
 gem "jev-feels"
 
 require "feels"
+using Jev::Feels
 
 Jev.configure do |config|
   config.api_key = ENV.fetch("JEV_API_KEY")
@@ -14,67 +15,84 @@ 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"
+if email.body.feels?(:urgent)
+  email.mark(:urgent)
 end
 ```
 
-## Ruby on Rails
-
-Gemfile, initializer, then an ordinary condition. Bundler loads the gem — no extra `require` unless you want sugar on `String`.
+The same idea continues for a decision and a scale:
 
 ```ruby
-# Gemfile
-gem "jev-feels"
+Jev.define :support_team,
+  "Which team should handle this?",
+  choices: {
+    billing: "payments and refunds",
+    technical: "bugs and outages",
+    sales: "purchase questions",
+    other: "none of the above"
+  }
+
+team = Jev.decide(email.body, :support_team)
 ```
 
 ```ruby
-# config/initializers/jev.rb
-Jev.configure do |config|
-  config.api_key = ENV.fetch("JEV_API_KEY")
-end
+Jev.define :severity,
+  "How severe is this issue?",
+  levels: {
+    minor: "minor inconvenience",
+    degraded: "workaround exists",
+    blocking: "cannot complete the task",
+    critical: "major outage or severe impact"
+  }
 
-Jev.define :urgent, "Requires immediate attention or action"
-Jev.define SupportEmail, :urgent, "Outage, customers cannot sign in"
-Jev.define Comment, :urgent, "Legal takedown or self-harm"
+severity = Jev.score(email.body, :severity)
 ```
 
+You do not need the Jev JSON wire format or the HTTP API for typical use. `Jev.measure` keeps the full typed result when you do.
+
+## Ruby on Rails
+
+Configure once, declare on the model, ask the record:
+
 ```ruby
-class SupportEmail < ApplicationRecord
-  def urgent?
-    Jev.feels?(body, SupportEmail, :urgent)
-  end
-end
+# Gemfile
+gem "jev-feels"
 ```
 
-To use `#feels?` on strings across the app, require the String extension in the initializer:
-
 ```ruby
 # config/initializers/jev.rb
-require "jev-feels/string"
+require "feels/active_model"
 
 Jev.configure do |config|
   config.api_key = ENV.fetch("JEV_API_KEY")
 end
 
 Jev.define :urgent, "Requires immediate attention or action"
-Jev.define SupportEmail, :urgent, "Outage, customers cannot sign in"
+Jev.define :support_team, "Which team should handle this?", choices: {
+  billing: "payments and refunds",
+  technical: "bugs and outages",
+  other: "none of the above"
+}
 ```
 
 ```ruby
 class SupportEmail < ApplicationRecord
-  def urgent?
-    body.feels?(SupportEmail, :urgent)
-  end
+  include Jev::Model
+
+  feels :body, :urgent # Get definition from initializer
+  feels :subject, :not_important, "Subject of this email is not important" # Or define in model
+  decide :body, :support_team
+
+  validates_feeling :body, :urgent, threshold: 0.9
 end
+
+email.feels?(:urgent)
+email.feels?(:not_important)
+email.decide(:support_team)
 ```
 
+The class is the scope, the first argument is the field. `validates_feeling` accepts `allow_nil:`, `allow_blank:`, `if:`, `unless:`, `on:`, `message:`, `at_least:`. If those skip the check, there is no HTTP call. A `nil` from `at_least:` is a validation failure.
+
 ## String sugar
 
 `require "feels"` does not change `String`. Opt in with a refinement:
@@ -82,7 +100,9 @@ end
 ```ruby
 using Jev::Feels
 
-email.feels?(:urgent)
+email.body.feels?(:urgent)
+email.body.decide(:support_team)
+email.body.score(:severity)
 ```
 
 Or, if you really want a global patch:
@@ -90,73 +110,242 @@ Or, if you really want a global patch:
 ```ruby
 require "feels/string"
 # or: require "jev-feels/string"
-
-email.feels?(:urgent)
 ```
 
-## Probability vs predicate
+## Definitions
 
-```ruby
-email.feels(:urgent)
-# => 0.94
+`Jev.define` is the vocabulary of the app. A symbol without extras is a yes/no check:
 
-email.feels?(:urgent)
-# => true
+```ruby
+Jev.define :urgent, "Requires immediate attention or action"
+Jev.define :spam, "Unsolicited or unwanted promotional content"
 ```
 
-`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`.
+A decision (`decide`):
 
 ```ruby
-email.feels?(:urgent, threshold: 0.8)
+Jev.define :support_team,
+  "Which support team should handle this?",
+  choices: {
+    billing: "payments, invoices, charges and refunds",
+    technical: "bugs, outages and integrations",
+    sales: "purchase and plan questions",
+    other: "none of the above"
+  }
 ```
 
-## Ad-hoc predicates
-
-A `String` predicate is used as-is and is **not** registered:
+A scale (`score`). Hash order is low to high:
 
 ```ruby
-email.feels?("sounds like the sender is about to cancel their subscription")
+Jev.define :severity,
+  "How severe is this customer issue?",
+  levels: {
+    cosmetic: "minor visual or cosmetic issue",
+    degraded: "functionality is degraded but a workaround exists",
+    blocking: "the customer cannot complete an important task",
+    critical: "major outage, data loss, security issue, or severe business impact"
+  }
 ```
 
-A `Symbol` must already have a definition or you get `Jev::UndefinedDefinition`.
-
-## Definitions
+Scoped names still work:
 
 ```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.define Email, :urgent, "Outage, customers cannot sign in"
 Jev.define Comment, :urgent, "Legal takedown or self-harm"
 
 Jev.definition(:urgent)
 Jev.definition(Email, :urgent)
 Jev.definitions
-Jev.definitions(Email)
+Jev.definitions(Comment)
 ```
 
-`define` replaces an existing name in that scope. `Jev.feels?(text, Email, :urgent)` uses the Email definition, then falls back to the global `:urgent` if Email has none. `definitions` / `definitions(Email)` return frozen copies.
+`define` replaces an existing name in that scope. Scopes are stored by class name, so `Email`, `"Email"` and `:Email` are the same key. A yes/no definition reads back as its instruction string. `choices:` / `levels:` read back as a `Jev::Definition`. On a Rails model, `feels` / `decide` / `score` bind a field; see [Ruby on Rails](#ruby-on-rails).
 
-## Configuration
+A `Symbol` must already have a definition or you get `Jev::UndefinedDefinition`. A `String` is an ad-hoc question and is not registered.
+
+## Asking
 
 ```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
+Jev.feels(email.body, :urgent)   # => 0.93
+Jev.feels?(email.body, :urgent)  # => true / false
+Jev.decide(ticket, :support_team) # => :billing
+Jev.score(ticket, :severity)      # => 2.37
 ```
 
-For tests, inject a transport and skip the network:
+`feels` is the calibrated probability (`0.0..1.0`). `feels?` is `feels >= threshold`. The default threshold is `0.5`.
 
 ```ruby
-Jev.configure do |config|
-  config.transport = ->(_payload) {
-    { "answers" => { "feels" => { "type" => "noul", "noul" => 0.9 } } }
+email.body.feels?(:urgent, threshold: 0.8)
+```
+
+`decide` returns the winning Symbol. `score` returns the fractional ordinal position — not a percentage.
+
+Ad-hoc questions skip `define`:
+
+```ruby
+email.body.feels?("sounds like the sender is about to cancel their subscription")
+
+Jev.decide(
+  ticket,
+  "Which support team should handle this?",
+  choices: {
+    billing: "payments and refunds",
+    technical: "bugs and outages",
+    other: "none of the above"
   }
+)
+```
+
+`Jev.feels?(text, Email, :urgent)` uses Email's definition, then a superclass, then the global `:urgent`.
+
+## Uncertainty
+
+`threshold:` is a single true/false cut. `0.51` and `0.99` are the same `true`.
+
+`at_least:` is minimum certainty in either direction. The middle band is `nil`:
+
+```ruby
+text.feels?(:urgent, at_least: 0.8)
+# p >= 0.8       => true
+# p <= 0.2       => false
+# 0.2 < p < 0.8  => nil
+```
+
+Without `at_least:`, `feels?` is still always true or false.
+
+Do not pass both `threshold:` and `at_least:`.
+
+`decide` uses confidence, which is not the winner's probability:
+
+```ruby
+Jev.decide(ticket, :support_team, confidence: 0.8)
+# => :billing or nil
+```
+
+## Typed results
+
+Convenience methods collapse a result. `measure` keeps the rest:
+
+```ruby
+result = Jev.measure(ticket, :urgent)
+result.probability
+result.type # => :noul
+
+result = Jev.measure(ticket, :support_team)
+result.choice
+result.confidence
+result.probabilities
+result.type # => :choice
+
+result = Jev.measure(ticket, :severity)
+result.score
+result.confidence
+result.probabilities
+result.levels
+result.level # => :blocking
+result.type  # => :score
+```
+
+```ruby
+feels?  # boolean, or nil with at_least:
+feels   # probability
+decide  # Symbol, or nil with confidence:
+score   # Float
+```
+
+## Batch
+
+Several questions, one Jev request, one `state`:
+
+```ruby
+result = Jev.measure(ticket) do |q|
+  q.feels :urgent
+  q.feels :angry
+  q.decide :support_team
+  q.score :severity
+end
+
+result[:urgent]        # => Jev::Result::Noul
+result[:support_team]  # => Jev::Result::Choice
+result[:severity]      # => Jev::Result::Score
+
+result.to_h
+# => { urgent: true, angry: false, support_team: :billing, severity: 2.37 }
+```
+
+A batch only uses defined names. Ad-hoc strings stay on a single `feels?` / `decide` / `score`.
+
+## Pattern matching
+
+`Jev::Result::Batch` uses collapsed values. No extra HTTP calls:
+
+```ruby
+case Jev.measure(ticket) { |q|
+  q.feels :urgent
+  q.decide :support_team
+  q.score :severity
+}
+in { urgent: true, support_team: :billing }
+  escalate_billing(ticket)
+in { support_team: :technical }
+  route_to_technical(ticket)
+in { urgent: true, severity: 2.0.. }
+  escalate(ticket)
+else
+  manual_review(ticket)
+end
+```
+
+`feels?` collapses to `true`/`false`, `decide` to a Symbol, `score` stays a Float so ranges work.
+
+## `Jev.match`
+
+A small dispatch for one `decide`. Low confidence goes to `otherwise`:
+
+```ruby
+Jev.match(ticket, :support_team) do
+  on(:billing)   { route_to_billing(ticket) }
+  on(:technical) { route_to_technical(ticket) }
+  on(:sales)     { route_to_sales(ticket) }
+  otherwise      { manual_review(ticket) }
+end
+
+Jev.match(ticket, :support_team, confidence: 0.8) do
+  on(:billing, :sales) { route_to_commercial(ticket) }
+  otherwise            { manual_review(ticket) }
+end
+```
+
+## Tests: stub, record, replay
+
+Stub by definition name. The block restores the previous transport, including in other threads:
+
+```ruby
+Jev.stub(
+  urgent: 0.95,
+  support_team: :billing,
+  severity: 2.4
+) do
+  expect(ticket.feels?(:urgent)).to be(true)
+  expect(Jev.decide(ticket, :support_team)).to eq(:billing)
+end
+```
+
+A full `decide` / `score` stub is a hash with `choice` or `score`, plus `confidence` and `probabilities`. To own the HTTP shape, set `config.transport`.
+
+Record real answers and replay them later. Replay never uses the network. The tape matches the request (state and questions), not a queue index. API keys and Authorization headers are not stored.
+
+```ruby
+tape = Jev.record do
+  ticket.feels?(:urgent)
+  Jev.decide(ticket, :support_team)
+end
+
+json = tape.to_json
+
+Jev.replay(tape) do
+  ticket.feels?(:urgent)
+  Jev.decide(ticket, :support_team)
 end
 ```
 
@@ -165,19 +354,32 @@ Jev.reset_configuration!
 Jev.reset_definitions!
 ```
 
+## Configuration
+
+```ruby
+Jev.configure do |config|
+  config.api_key = ENV["JEV_API_KEY"]
+end
+```
+
+`base_url` defaults to `https://api.typesafe.ai`, `timeout` to 10 seconds, `threshold` to `0.5`. Override only if you need to.
+
 ## 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 |
+| 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 |
+| `Jev::ReplayError`          | Replay tape does not contain this request     |
+
+Malformed definitions (`choices:` and `levels:` together, empty Choice, too few Score levels, duplicate keys, invalid `threshold:` / `at_least:` / `confidence:`) raise `ArgumentError`.
 
 ## 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?`.
+[Jev](https://docs.typesafe.ai/introduction.md) / TypeSafe System One. `POST https://api.typesafe.ai/v1/systemone`. That is an implementation detail. The public API is `Jev.feels` / `Jev.feels?` / `Jev.decide` / `Jev.score` / `Jev.measure` / `Jev.match`.

data/context7.json

@@ -1,6 +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.",
+  "description": "Semantic decisions as ordinary Ruby. Jev.define :urgent, then text.feels?(:urgent), model.decide(:support_team), model.score(:severity), and Jev.measure for typed or batched results. Jev stays an implementation detail.",
   "excludeFolders": ["spec"]
 }

data/lib/feels/active_model.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "feels"
+require "active_model"
+require_relative "../jev/active_model"

data/lib/feels/string.rb

@@ -10,4 +10,16 @@ class String
   def feels?(...)
     Jev.feels?(self, ...)
   end
+
+  def decide(...)
+    Jev.decide(self, ...)
+  end
+
+  def score(...)
+    Jev.score(self, ...)
+  end
+
+  def measure(...)
+    Jev.measure(self, ...)
+  end
 end

data/lib/jev/active_model.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Jev
+  module ActiveModel
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def validates_feeling(attribute, predicate, message: nil, threshold: nil, at_least: nil, **options)
+        feeling = { predicate: predicate, message: message, threshold: threshold, at_least: at_least }
+        validates_each(attribute, **options) do |record, attr, value|
+          Jev::ActiveModel.validate(record, attr, value, feeling)
+        end
+      end
+    end
+
+    def self.validate(record, attr, value, feeling)
+      text = value.is_a?(String) ? value : value.to_s
+      kwargs = feeling.slice(:threshold, :at_least).compact
+      return if Jev.feels?(text, feeling[:predicate], **kwargs) == true
+
+      record.errors.add(attr, feeling[:message] || "is not #{feeling[:predicate]}")
+    end
+  end
+end
+
+if defined?(ActiveModel::Validations::HelperMethods)
+  ActiveModel::Validations::HelperMethods.include(Jev::ActiveModel::ClassMethods)
+end

data/lib/jev/client.rb

@@ -9,46 +9,42 @@ module Jev
       @configuration = configuration
     end
 
+    def ask(text, questions)
+      body = transport.call(payload(text, questions))
+      parse(body, questions)
+    end
+
     def probability(text, instructions)
-      extract_noul(transport.call(payload(text, instructions)))
+      definition = Definition.build(name: :feels, instructions: instructions)
+      ask(text, { QUESTION_ID => definition }).fetch(QUESTION_ID).probability
     end
 
     private
 
     def transport
-      @configuration.transport || Transport.new(@configuration)
+      Harness.current_transport(@configuration)
     end
 
-    def payload(text, instructions)
+    def payload(text, questions)
       {
         "model" => MODEL,
         "state" => text,
-        "questions" => {
-          QUESTION_ID => {
-            "type" => "noul",
-            "instructions" => instructions
-          }
-        }
+        "questions" => questions.to_h { |id, definition| [id, definition.to_question] }
       }
     end
 
-    def extract_noul(body)
+    def parse(body, questions)
       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?
+      questions.to_h do |id, definition|
+        answer = answers[id]
+        raise InvalidResponseError, "Jev response is missing the #{id} answer" unless answer.is_a?(Hash)
 
-      # ponytail: clamp out-of-range noul; raise if Jev starts returning uncalibrated values
-      noul.clamp(0.0, 1.0)
+        [id, Result.parse(answer, definition)]
+      end
     end
   end
 end