feelings 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6ea114c41b7209ab7464a90648496db559758e2c2b227d0e84bb83cc4381331
+  data.tar.gz: ce9a7258312c3501aee7eb748e9e157b218afed0a8fb689f57d156d173573fe8
+SHA512:
+  metadata.gz: 41d0a2e969d98fe47b788d92736b0cda09e6a1420cd7acb1c3b5b1f085dbede5d1520f14954b0a400596c808b3dcf7e0aac91d5ff3d801907ed15683536e7b99
+  data.tar.gz: 1857417a1c55ca4888e025e470ae321e1f0777f77ae68febb4dbe0bae186e4f35bcb22f4932b5e864e210014f5673fab61abac3b52849c7256338a27b5ab01f6

data/.ruby-version

@@ -0,0 +1 @@
+3.3.4

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.0.1
+
+- Initial release. `Feelings(value).like?`, `.like`, `.most_like`, `.pick`, and `.match` for
+  probabilistic conditionals backed by a decision model. YAML-backed label registry, hash
+  batching into a single request, `Feelings.while` for bounded loops, `Feelings.chaos` for
+  distribution sampling, and `Feelings.record` / `Feelings.replay` for tapes. Default judge is
+  `RubyDecisionModel.client`; ships with a `Feelings::Judges::Stub` for tests and an optional
+  Rails railtie.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obie Fernandez
+
+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,181 @@
+# feelings
+
+A decision model can answer a typed question about a value with a calibrated probability.
+[Probably](https://probably-lang.southpolesteve.workers.dev/) showed what code reads like when
+an `if` can ask one of those questions directly instead of hand-rolling a prompt. `feelings`
+brings that construct, `feels`, to Ruby. Inspired by Probably.
+
+It works with Jev through OpenRouter or Typesafe's API via
+[ruby_decision_model](https://rubygems.org/gems/ruby_decision_model), the default judge.
+
+## Install
+
+```ruby
+gem "feelings"
+```
+
+## Setup
+
+No configuration is required beyond an API key. Set `OPENROUTER_API_KEY` or
+`TYPESAFE_API_KEY` in your environment and `feelings` picks a judge automatically the first
+time you ask it something.
+
+```ruby
+require "feelings"
+
+Feelings("that email").like?("genuinely urgent")
+# => true or false
+```
+
+## like? and like
+
+`like?` asks a yes/no question about a value.
+
+```ruby
+f = Feelings(email.body)
+f.like?("spam")
+```
+
+`like` returns a `Mood` you can branch on. Declare a `maybe` branch and the yes/maybe/no split
+widens to 0.3/0.7 automatically, so an ambiguous answer has somewhere to go.
+
+```ruby
+f.like("full of corporate jargon") do |mood|
+  mood.yes   { rewrite(draft) }
+  mood.maybe { flag_for_review(draft) }
+  mood.no    { draft }
+end
+```
+
+Pass `at_least:` to set your own probability floor instead. `like?` then returns `nil` for the
+middle zone rather than forcing a guess.
+
+```ruby
+f.like?("a security incident", at_least: 0.8) # true, false, or nil
+```
+
+## most_like
+
+`most_like` picks the best-fitting label out of a set and hands back the winning symbol.
+
+```ruby
+KINDS = { invitation: "an invitation to an event", sales_pitch: "someone selling something" }
+Feelings(email).most_like(KINDS) # => :invitation
+```
+
+Pass `confidence:` to get `nil` back instead of a shaky guess.
+
+## YAML registry
+
+Keep your descriptions and label sets out of the codebase and load them once.
+
+```yaml
+# config/feelings.yml
+kinds:
+  invitation: an invitation to an event
+  sales_pitch: someone selling something
+  other: anything else
+spam: an unsolicited commercial email
+```
+
+```ruby
+Feelings.load("config/feelings.yml")
+Feelings(email).like?(:spam)        # uses the registered description
+Feelings(email).most_like(:kinds)   # uses the registered label set
+```
+
+YAML loading is lazy, so plain `require "feelings"` never pulls in the YAML library. You can also
+register descriptions straight from Ruby without touching a file:
+
+```ruby
+Feelings.register(spam: "an unsolicited commercial email", kinds: KINDS)
+```
+
+Every construct works fine with an empty registry and no config file. `Feelings.load` and
+`Feelings.register` can both be called more than once; later calls override earlier keys.
+
+## Hash batching
+
+Any `like?` or `like` call given a Hash asks everything it names in one request.
+
+```ruby
+Feelings(email).like?(spam: "spam", urgent: :urgent, kind: :kinds)
+# => { spam: false, urgent: true, kind: :invitation }
+```
+
+## match
+
+`match` dispatches on the winning label with a block, inline descriptions included.
+
+```ruby
+Feelings(email).match(KINDS) do
+  on(:invitation) { accept_invite(email) }
+  on(:sales_pitch, :other) { archive(email) }
+  otherwise { flag_for_review(email) }
+end
+```
+
+## Feelings.while
+
+A bounded loop that keeps calling your block while a value still feels a certain way.
+
+```ruby
+draft = Feelings.while(draft, "full of corporate jargon", max: 5) { |current| rewrite(current) }
+```
+
+It raises `Feelings::LoopLimit` if the value still feels that way after `max` iterations.
+
+## Chaos
+
+`Feelings.chaos` samples from the answer's probability distribution instead of always taking
+the top pick, useful for simulations and load-testing prompts.
+
+```ruby
+Feelings.chaos { Feelings(email).most_like(KINDS) }
+```
+
+## Record and replay
+
+Record a real run once, then replay it in tests without ever calling a judge again.
+
+```ruby
+tape = Feelings.record { Feelings(email).like?("spam") }
+Feelings.replay(tape) { Feelings(email).like?("spam") } # judge is never called
+```
+
+A tape round-trips through JSON with `tape.to_json` and `Feelings::Tape.from_json`.
+
+## Core extension
+
+```ruby
+require "feelings/core_ext"
+
+email.feels_like?("spam")
+email.feels_most_like(KINDS)
+```
+
+## Testing with Stub
+
+```ruby
+Feelings.judge = Feelings::Judges::Stub.new("spam" => 0.9, kinds: :invitation)
+Feelings(email).like?("spam") # => true, no network call
+```
+
+## Status
+
+0.0.1. The API above is the whole surface.
+
+## Releasing
+
+Publishing runs through RubyGems trusted publishing, so no API key is stored
+anywhere. To ship a version:
+
+1. Bump `lib/feelings/version.rb`.
+2. Add the version to `CHANGELOG.md`.
+3. Merge to `main`. The Release workflow runs the suite, builds the gem with
+   `gem build --strict`, checks the built gem carries every file under
+   `lib/`, and pushes it. A version already on RubyGems is skipped, so the
+   workflow is safe to re-run.
+
+The same workflow can be started by hand from the Actions tab or with
+`gh workflow run release.yml`.

data/Rakefile

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test
+
+# Release tooling, the single-gem shape of the terret repo's rake release
+# tasks. The gemspec is the one source of name and version; nothing here
+# hardcodes either. The release workflow drives these three tasks in order.
+namespace :release do
+  gemspec = -> { Gem::Specification.load(Dir["*.gemspec"].first) }
+
+  published = lambda do |spec|
+    require "open-uri"
+    require "json"
+    body = URI.open("https://rubygems.org/api/v1/versions/#{spec.name}.json", &:read)
+    JSON.parse(body).any? { |v| v["number"] == spec.version.to_s }
+  rescue OpenURI::HTTPError
+    false # 404 => the gem has never been published, so there is nothing to skip
+  end
+
+  desc "Build the gem into pkg/ with --strict (proof the gemspec is valid). " \
+       "Reversible, pkg/ is gitignored, and the local half of a release; " \
+       "release:push is the irreversible half."
+  task :build do
+    require "fileutils"
+    spec = gemspec.call
+    FileUtils.rm_rf("pkg")
+    FileUtils.mkdir_p("pkg")
+    # --strict escalates any spec warning to a build failure.
+    sh "gem build #{File.basename(spec.loaded_from)} --strict --output pkg/#{spec.name}-#{spec.version}.gem"
+  end
+
+  desc "Print publish=true when the gemspec's version is not yet on RubyGems " \
+       "and publish=false when it is. The release workflow reads this to decide " \
+       "whether to fetch credentials and push at all."
+  task :status do
+    puts "publish=#{!published.call(gemspec.call)}"
+  end
+
+  desc "Push pkg/<gem>-<version>.gem to RubyGems. A version already published " \
+       "is skipped, so a re-run is safe. The release workflow runs this with a " \
+       "short-lived key from trusted publishing; by hand it needs RubyGems MFA."
+  task :push do
+    spec = gemspec.call
+    gem_file = "pkg/#{spec.name}-#{spec.version}.gem"
+    abort "release:push: #{gem_file} is missing, run `rake release:build` first" unless File.exist?(gem_file)
+
+    if published.call(spec)
+      puts "skip  #{spec.name} #{spec.version} (already on RubyGems)"
+      next
+    end
+
+    puts "push  #{gem_file}"
+    sh "gem push #{gem_file}"
+  end
+end

data/feelings.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/feelings/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "feelings"
+  spec.version = Feelings::VERSION
+  spec.authors = ["Obie Fernandez"]
+  spec.email = ["obiefernandez@gmail.com"]
+
+  spec.summary = "Probabilistic conditionals for Ruby: Feelings(message).like?(\"genuinely urgent\")"
+  spec.description = <<~DESC.strip.gsub(/\n/, " ")
+    feelings brings the feels construct from the Probably language to Ruby. A decision
+    model judges how well a description fits a value, and feelings turns that into
+    conditionals, semantic match, bounded loops, chaos sampling, and replayable tapes.
+    Descriptions and label sets can live in YAML. Works with any judge; ruby_decision_model
+    is the default.
+  DESC
+  spec.homepage = "https://github.com/obie/feelings"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "ruby_decision_model", "~> 0.1"
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

data/lib/feelings/about.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Feelings
+  # The wrapper returned by Feelings(value). Holds the value and memoizes
+  # answers per question so asking the same thing twice never re-judges.
+  class About
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+      @resolved_state = State.resolve(value)
+      @memo = {}
+    end
+
+    def like?(arg = nil, at_least: nil, confidence: nil, **rest)
+      hash = batch_hash(arg, rest)
+      if hash
+        return batch(hash, at_least: at_least, confidence: confidence).transform_values { |result| coerce_bool(result) }
+      end
+
+      ask_mood(arg, at_least: at_least).to_bool
+    end
+
+    def like(arg = nil, at_least: nil, confidence: nil, **rest, &block)
+      hash = batch_hash(arg, rest)
+      return batch(hash, at_least: at_least, confidence: confidence) if hash
+
+      mood = ask_mood(arg, at_least: at_least)
+      return mood unless block
+
+      mood.collect(&block)
+    end
+
+    def most_like(*args, confidence: nil, **rest)
+      args = args + [rest] unless rest.empty?
+      labels = build_label_set(args)
+      pick = ask_pick(labels, confidence: confidence)
+      pick&.label
+    end
+
+    def pick(*args, confidence: nil, **rest)
+      args = args + [rest] unless rest.empty?
+      labels = build_label_set(args)
+      ask_pick(labels, confidence: confidence)
+    end
+
+    def match(labels = nil, confidence: nil, &block)
+      builder = MatchBuilder.new
+      builder.instance_eval(&block) if block
+
+      merged = labels ? Labels.resolve(labels) : {}
+      builder.labels.each { |key, description| merged[key] = description }
+      builder.branches.each do |branch|
+        branch.keys.each { |key| merged[key] ||= Labels.description_for(key) }
+      end
+      Labels.validate!(merged)
+
+      pick = ask_pick(merged, confidence: confidence)
+      branch = pick && builder.branch_for(pick.label)
+
+      if branch
+        branch.block.call
+      elsif builder.otherwise
+        builder.otherwise.call
+      end
+    end
+
+    private
+
+    def batch_hash(arg, rest)
+      if arg.is_a?(Hash)
+        rest.empty? ? arg : arg.merge(rest)
+      elsif !rest.empty?
+        rest
+      end
+    end
+
+    def coerce_bool(result)
+      case result
+      when Mood
+        result.to_bool
+      when Pick
+        result.label
+      else
+        result
+      end
+    end
+
+    # Raw answers are memoized per question so a second ask with a different
+    # threshold reuses the judgment instead of paying for another request.
+    def ask_mood(description, at_least:)
+      resolved = resolve_description(description)
+      answer = @memo[[:noul, resolved]] ||=
+        Engine.call(value: @resolved_state, specs: { sole: { kind: :noul, description: resolved } })[:sole]
+      build_mood(answer, resolved, at_least: at_least)
+    end
+
+    def ask_pick(labels, confidence:)
+      answer = @memo[[:choice, labels]] ||=
+        Engine.call(value: @resolved_state, specs: { sole: { kind: :choice, labels: labels } })[:sole]
+      build_pick(answer, confidence: confidence)
+    end
+
+    def build_mood(answer, description, at_least:)
+      Mood.new(
+        probability: answer[:probability],
+        description: description,
+        value: value,
+        model: answer[:model],
+        at_least: at_least,
+        draw: answer[:draw]
+      )
+    end
+
+    def build_pick(answer, confidence:)
+      pick = Pick.new(
+        label: answer[:choice],
+        confidence: answer[:confidence],
+        probabilities: answer[:probabilities],
+        model: answer[:model]
+      )
+      return nil if confidence && pick.confidence < confidence
+
+      pick
+    end
+
+    def batch(hash, at_least: nil, confidence: nil)
+      specs = {}
+      descriptions = {}
+
+      hash.each do |id, raw|
+        kind, payload = classify_value(raw)
+        if kind == :noul
+          specs[id] = { kind: :noul, description: payload }
+          descriptions[id] = payload
+        else
+          specs[id] = { kind: :choice, labels: payload }
+        end
+      end
+
+      answers = Engine.call(value: @resolved_state, specs: specs)
+      answers.each_with_object({}) do |(id, answer), results|
+        results[id] = if specs[id][:kind] == :noul
+                         build_mood(answer, descriptions[id], at_least: at_least)
+                       else
+                         build_pick(answer, confidence: confidence)
+                       end
+      end
+    end
+
+    def classify_value(raw)
+      case raw
+      when String
+        [:noul, raw]
+      when Hash, Array
+        [:choice, Labels.resolve(raw)]
+      when Symbol
+        registered = Feelings[raw]
+        if registered.is_a?(Hash)
+          [:choice, Labels.resolve(registered)]
+        else
+          [:noul, registered.is_a?(String) ? registered : Labels.humanize(raw)]
+        end
+      else
+        raise ArgumentError, "unsupported question value #{raw.inspect}"
+      end
+    end
+
+    def resolve_description(description)
+      case description
+      when String
+        description
+      when Symbol
+        registered = Feelings[description]
+        registered.is_a?(String) || registered.is_a?(Hash) ? registered : Labels.humanize(description)
+      else
+        raise ArgumentError, "description must be a String or Symbol, got #{description.class}"
+      end
+    end
+
+    def build_label_set(args)
+      labels =
+        if args.size == 1 && (args.first.is_a?(Symbol) || args.first.is_a?(Array) || args.first.is_a?(Hash))
+          Labels.resolve(args.first)
+        else
+          args.each_with_object({}) do |arg, hash|
+            case arg
+            when Symbol
+              hash[arg] = Labels.description_for(arg)
+            when Hash
+              arg.each { |key, description| hash[key.to_sym] = description }
+            else
+              raise BadLabels, "unsupported label argument #{arg.inspect}"
+            end
+          end
+        end
+
+      Labels.validate!(labels)
+    end
+  end
+end

data/lib/feelings/core_ext.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "../feelings"
+
+class Object
+  def feels_like?(...)
+    Feelings(self).like?(...)
+  end
+
+  def feels_like(...)
+    Feelings(self).like(...)
+  end
+
+  def feels_most_like(...)
+    Feelings(self).most_like(...)
+  end
+end

data/lib/feelings/distribution.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Feelings
+  # Helpers for turning a probability spread into a normalized distribution
+  # and sampling from it, used by Feelings.chaos.
+  module Distribution
+    TOLERANCE = 0.02
+
+    module_function
+
+    def normalize(probabilities)
+      raise InvalidDistribution, "distribution must not be empty" if probabilities.nil? || probabilities.empty?
+
+      floats = probabilities.transform_values(&:to_f)
+      sum = floats.values.sum
+
+      if sum.zero?
+        even = 1.0 / floats.size
+        return floats.transform_values { even }
+      end
+
+      unless (sum - 1.0).abs <= TOLERANCE
+        raise InvalidDistribution, "distribution sums to #{sum}, expected roughly 1.0"
+      end
+
+      floats.transform_values { |v| v / sum }
+    end
+
+    def sample(probabilities, draw)
+      normalized = normalize(probabilities)
+      cumulative = 0.0
+      normalized.each do |key, probability|
+        cumulative += probability
+        return key if draw < cumulative
+      end
+      normalized.keys.last
+    end
+  end
+end