typesafe-jev 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7645167a374f6815e9a4ee6b96b56d54f611a3a08b274467f963dedd66e786ca
+  data.tar.gz: 0d66633fe64b5061b9f1bf7cb59fdf74f73d711c332bb34f7bbf0be1a042b85c
+SHA512:
+  metadata.gz: 6de70dbd0412a10808feb2f79e1635462056a0c8069306b3fd063167b15ff0e6706f64fc22719e3cdd47f21a3fff4a70c64d368660eb1491c5abd5b4240e7baf
+  data.tar.gz: fd391b3ecd54101ea40a0923d618ee6e9a884ae54c3c9876d9e3ef5ed3f3a8741b81b7ae032ebe3cf9e109cdf96df468bd3741995c94a6d0b949266ed2711622

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 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`.
+
+## 0.1.0
+
+- Initial gem scaffold.

data/README.md

@@ -0,0 +1,14 @@
+# typesafe-jev
+
+Ruby client for [Jev](https://docs.typesafe.ai), TypeSafe's System One model — starting point, under construction.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/typesafe/choice.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # A question that selects one option from a defined, unordered set.
+  # The answer includes the selected option, the probability distribution
+  # across all options, and a confidence.
+  #
+  #   Typesafe::Choice.new("Which team should handle this?",
+  #                        criteria: {
+  #                          billing: "Payment or subscription issues",
+  #                          technical: "Bugs or integration problems"
+  #                        })
+  class Choice < Question
+    # @return [Hash] the option keys mapped to their descriptions.
+    attr_reader :criteria
+
+    # @param instructions [String] the question asked about the state.
+    # @param criteria [Hash] the options: keys (String or Symbol) mapped to
+    #   non-empty String descriptions.
+    def initialize(instructions, criteria:)
+      @criteria = normalize_criteria(criteria)
+      super(instructions)
+    end
+
+    def type
+      "choice"
+    end
+
+    def to_h
+      super.merge(criteria: @criteria)
+    end
+
+    private
+
+    def normalize_criteria(criteria)
+      unless criteria.is_a?(Hash) && !criteria.empty?
+        raise ArgumentError, "criteria must be a non-empty Hash of option keys to descriptions"
+      end
+
+      criteria.each_with_object({}) do |(key, value), normalized|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise ArgumentError, "criteria keys must be Strings or Symbols"
+        end
+
+        normalized[key] = validate_string(value, "criteria[#{key.inspect}]")
+      end.freeze
+    end
+  end
+end

data/lib/typesafe/noul.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # A yes/no question. The answer is the probability that the answer is yes.
+  #
+  #   Typesafe::Noul.new("Does the customer request a refund?")
+  #
+  # +criteria+ optionally clarifies what yes and no mean:
+  #
+  #   Typesafe::Noul.new("Is the message urgent?",
+  #                      criteria: { true: "Conveys urgency", false: "No time pressure" })
+  class Noul < Question
+    # @return [Hash, nil] the optional +{ true:, false: }+ descriptions.
+    attr_reader :criteria
+
+    # @param instructions [String] the yes/no question asked about the state.
+    # @param criteria [Hash, nil] optional +{ true:, false: }+ descriptions of
+    #   what yes and no mean. Keys may be Strings or Symbols and are
+    #   normalized to Symbols.
+    def initialize(instructions, criteria: nil)
+      @criteria = criteria.nil? ? nil : normalize_criteria(criteria)
+      super(instructions)
+    end
+
+    def type
+      "noul"
+    end
+
+    # @return [Hash] the API shape; +criteria+ is omitted when not given.
+    def to_h
+      @criteria ? super.merge(criteria: @criteria) : super
+    end
+
+    private
+
+    def normalize_criteria(criteria)
+      unless criteria.is_a?(Hash)
+        raise ArgumentError, "criteria must be a Hash with :true and :false keys"
+      end
+
+      normalized = {}
+      criteria.each do |key, value|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise ArgumentError, "criteria keys must be Strings or Symbols"
+        end
+
+        sym = key.to_sym
+        raise ArgumentError, "criteria has duplicate key #{sym.inspect}" if normalized.key?(sym)
+
+        normalized[sym] = validate_string(value, "criteria[#{key.inspect}]")
+      end
+
+      unless normalized.keys.sort == %i[false true]
+        raise ArgumentError, "criteria must have exactly :true and :false keys"
+      end
+
+      normalized.freeze
+    end
+  end
+end

data/lib/typesafe/question.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # Abstract base class for the three question types understood by the
+  # TypeSafe System One API: {Noul}, {Choice}, and {Score}.
+  #
+  # A question is an immutable value object. The question ID used to identify
+  # its answer is not part of the object: it is the Hash key under which the
+  # question is sent in a request, e.g.
+  #
+  #   questions = { refund_requested: Typesafe::Noul.new("Does the customer request a refund?") }
+  class Question
+    # @return [String] the question asked about the state.
+    attr_reader :instructions
+
+    # @param instructions [String] the question asked about the state.
+    # @raise [ArgumentError] if +instructions+ is not a non-empty String.
+    def initialize(instructions)
+      unless instructions.is_a?(String) && !instructions.strip.empty?
+        raise ArgumentError, "instructions must be a non-empty String"
+      end
+
+      @instructions = instructions.dup.freeze
+      validate!
+      freeze
+    end
+
+    # @return [String] the API question type tag ("noul", "choice", or "score").
+    # @raise [NotImplementedError] on the abstract base class.
+    def type
+      raise NotImplementedError, "#{self.class} must implement #type"
+    end
+
+    # @return [Hash] the question shape expected by the TypeSafe API.
+    def to_h
+      { type: type, instructions: instructions }
+    end
+
+    # @return [String] the question serialized as JSON for the TypeSafe API.
+    def to_json(state = nil)
+      JSON.generate(to_h, state)
+    end
+
+    # Questions compare equal when they are of the same class and serialize
+    # to the same API shape.
+    def ==(other)
+      other.class == self.class && other.to_h == to_h
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, to_h].hash
+    end
+
+    private
+
+    # Hook for subclasses to validate their own attributes before freezing.
+    def validate!; end
+
+    # Validates that +value+ is a non-empty String and returns a frozen copy.
+    def validate_string(value, name)
+      unless value.is_a?(String) && !value.strip.empty?
+        raise ArgumentError, "#{name} must be a non-empty String"
+      end
+
+      value.dup.freeze
+    end
+  end
+end

data/lib/typesafe/score.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Typesafe
+  # A question that positions the state along an ordered spectrum of levels.
+  # The answer includes the score, the legend (levels by number), the
+  # probability distribution across levels, and a confidence.
+  #
+  #   Typesafe::Score.new("How frustrated is the customer?",
+  #                       criteria: [
+  #                         "Calm, just stating facts",
+  #                         "Frustrated but civil",
+  #                         "Very angry, strong language"
+  #                       ])
+  class Score < Question
+    # @return [Array<String>] the ordered levels of the spectrum.
+    attr_reader :criteria
+
+    # @param instructions [String] the question asked about the state.
+    # @param criteria [Array<String>] the ordered levels; a non-empty array
+    #   of non-empty Strings, ordered from lowest to highest.
+    def initialize(instructions, criteria:)
+      @criteria = normalize_criteria(criteria)
+      super(instructions)
+    end
+
+    def type
+      "score"
+    end
+
+    def to_h
+      super.merge(criteria: @criteria)
+    end
+
+    private
+
+    def normalize_criteria(criteria)
+      unless criteria.is_a?(Array) && !criteria.empty?
+        raise ArgumentError, "criteria must be a non-empty Array of Strings"
+      end
+
+      criteria.each_with_index.map do |level, index|
+        validate_string(level, "criteria[#{index}]")
+      end.freeze
+    end
+  end
+end

data/lib/typesafe/version.rb

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

data/lib/typesafe.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "typesafe/version"
+require_relative "typesafe/question"
+require_relative "typesafe/noul"
+require_relative "typesafe/choice"
+require_relative "typesafe/score"
+
+module Typesafe
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: typesafe-jev
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- dtheo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: Use Jev, TypeSafe's System One model, from Ruby or Rails.
+email:
+- dtheo@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/typesafe.rb
+- lib/typesafe/choice.rb
+- lib/typesafe/noul.rb
+- lib/typesafe/question.rb
+- lib/typesafe/score.rb
+- lib/typesafe/version.rb
+homepage: https://docs.typesafe.ai
+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
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for Jev, TypeSafe's System One model.
+test_files: []