ask-core 0.11.4 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe6fd73be561e63544265ffe4065905c432680e925c9df5d2e8b5e5f3e2b7896
-  data.tar.gz: 59389ca6fb4726cf9d921eff7cc35598c95c619154f97c7cfb85a844e8e9cc02
+  metadata.gz: 6fdffc37629602a70343da6bd60aaf87cfee10436f5b04283ef1efce46028393
+  data.tar.gz: 384f09f0ee5c310f82c8e137af71bb77634dcd6f3bad411a858797bc2129e1d8
 SHA512:
-  metadata.gz: b944d00f3194ab931e56e3d39ace11c6bb0b058c288dd147574c68a1369a10627d1982d75a4669d5a1eed9d225b2930082684e68086f54b10947503cfb90ae80
-  data.tar.gz: b83e78248a0a843718850c5333f339dae78b0c63881184da0902847fd360454fb58cebb1b6269dc2d94869968820d937a1e570473f3e5de96811f22221603ac8
+  metadata.gz: 2248010d045f7045986842c3b0d4d8fd7f908024db5c3d8d0f836a1f9bb8201496d1dd2bf26cc1107e7c26dbd16cd37bfa506a2f7ce60fc207cfee6fa860c719
+  data.tar.gz: a55c2603441a9591741c2996bad3b3cac0499fc5945cad8117ec82067274d67f2902a24e7ce922f3794578329ad05479eaef5691003df7ed573e97ce99a37737

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [0.12.0] - 2026-09-18
+
+### Added
+
+- **The decision vocabulary — `Ask::Decision`, `Ask::DecisionResult`,
+  `Ask::DecisionProvider`.** Typed questions that return structured answers
+  with calibrated probabilities: `Choice` (pick one of a defined set), `Score`
+  (a position on ordered levels), and `Noul` (a yes/no with a probability).
+  `DecisionProvider` is the registry that makes the backing engine swappable,
+  and `DecisionResult::Batch` answers a whole set of questions asked together.
+
+  The vocabulary lives in ask-core, and only the vocabulary: dependency-free
+  value objects every gem can speak, with no client, no retries and no
+  transport. The implementation is `ask-decisions`; a provider that talks to
+  TypeSafe/Jev, or to anything else, registers itself and is reachable from
+  everywhere the vocabulary is.
+
+  ```ruby
+  question = Ask::Decision::Choice.new(
+    instructions: "Which team should handle this?",
+    criteria: {billing: "Payment issues", technical: "Bugs or outages"}
+  )
+  provider.evaluate(state: "Charged twice for A-104", decisions: {"route" => question})
+  # => #<ChoiceAnswer choice="billing" confidence=0.89>
+  ```
+
+  New public API, so the minor version moves. Nothing existing changed.
+
 ## [0.10.0] - 2026-08-05
 
 ### Added

data/lib/ask/decision.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Ask
+  # Decision primitives — the vocabulary for typed questions that return structured
+  # answers with calibrated probabilities. The three types mirror TypeSafe's System
+  # One API: Choice, Score, and Noul.
+  #
+  # These are vendor-neutral value objects in ask-core so that every gem in the
+  # ecosystem can speak decisions without depending on a specific provider gem.
+  #
+  # @example A Choice question
+  #   Ask::Decision::Choice.new(
+  #     instructions: "Which team should handle this?",
+  #     criteria: { billing: "Payment issues", technical: "Bugs or outages" }
+  #   )
+  #
+  # @example A Noul question
+  #   Ask::Decision::Noul.new(
+  #     instructions: "Does this message express urgency?"
+  #   )
+  #
+  module Decision
+    # A Choice question: pick one option from a defined set.
+    #
+    # @attr_reader instructions [String] the question to evaluate
+    # @attr_reader criteria [Hash{String => String}] option → rubric description
+    class Choice
+      attr_reader :instructions, :criteria
+
+      def initialize(instructions:, criteria:)
+        @instructions = instructions
+        @criteria = criteria.freeze
+        freeze
+      end
+
+      def type = :choice
+
+      # Wire format for a single question entry.
+      def to_h
+        { type: "choice", instructions: instructions, criteria: criteria }
+      end
+    end
+
+    # A Score question: rate the state on ordered, descriptive levels.
+    #
+    # @attr_reader instructions [String] what to rate
+    # @attr_reader criteria [Array<String>] ordered level descriptions (≥2)
+    class Score
+      attr_reader :instructions, :criteria
+
+      def initialize(instructions:, criteria:)
+        @instructions = instructions
+        @criteria = Array(criteria).freeze
+        raise ArgumentError, "Score criteria must have at least 2 levels" if @criteria.size < 2
+        freeze
+      end
+
+      def type = :score
+
+      def to_h
+        { type: "score", instructions: instructions, criteria: criteria }
+      end
+    end
+
+    # A Noul question: is this statement true? Returns a probability (0–1).
+    #
+    # @attr_reader instructions [String] the yes/no question
+    # @attr_reader criteria [Hash, nil] optional { "true" => "...", "false" => "..." }
+    class Noul
+      attr_reader :instructions, :criteria
+
+      def initialize(instructions:, criteria: nil)
+        @instructions = instructions
+        @criteria = criteria&.freeze
+        freeze
+      end
+
+      def type = :noul
+
+      def to_h
+        h = { type: "noul", instructions: instructions }
+        h[:criteria] = criteria if criteria
+        h
+      end
+    end
+  end
+end

data/lib/ask/decision_provider.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Ask
+  # Abstract base class for decision providers. Mirrors Ask::Provider but for
+  # structured decisions (Choice / Score / Noul) instead of text generation.
+  #
+  # Subclasses implement {#evaluate} and register via {.register}. The active
+  # provider is resolved via {.resolve}.
+  #
+  # @example Registering a provider
+  #   Ask::DecisionProvider.register(:typesafe, Ask::Decisions::Typesafe)
+  #
+  # @example Resolving and using a provider
+  #   provider = Ask::DecisionProvider.resolve(:typesafe)
+  #   result = provider.evaluate(state: "...", decisions: { "q" => choice_q })
+  #
+  class DecisionProvider
+    REGISTRY_MUTEX = Mutex.new
+    private_constant :REGISTRY_MUTEX
+
+    # @return [Object] provider configuration
+    attr_reader :config
+
+    def initialize(config = {})
+      @config = config
+    end
+
+    # Evaluate a state against a map of decisions and return a Result::Batch.
+    #
+    # @param state [String, Hash, Array] the content to evaluate
+    # @param decisions [Hash{String => Decision::Choice|Decision::Score|Decision::Noul}]
+    #   map of id → question
+    # @param model [String, nil] model to use (provider-specific)
+    # @return [DecisionResult::Batch]
+    # @raise [NotImplementedError] in subclasses that don't implement this
+    def evaluate(state:, decisions:, model: nil)
+      raise NotImplementedError, "#{self.class} must implement #evaluate"
+    end
+
+    # --- Slug / name ---
+
+    def slug  = self.class.slug
+    def name  = self.class.name
+
+    # --- Registry (class-level) ---
+
+    class << self
+      def register(name, provider_class)
+        REGISTRY_MUTEX.synchronize { registry[name.to_sym] = provider_class }
+      end
+
+      def resolve(name)
+        REGISTRY_MUTEX.synchronize do
+          registry[name.to_sym] || raise(Ask::UnknownProvider,
+            "Unknown decision provider: #{name.inspect}. " \
+            "Available: #{registry.keys.join(', ')}")
+        end
+      end
+
+      def providers
+        REGISTRY_MUTEX.synchronize { registry.dup }
+      end
+
+      def clear_providers!
+        REGISTRY_MUTEX.synchronize { @registry = {} }
+      end
+
+      def slug
+        name.split("::").last.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+      end
+
+      def name
+        to_s.split("::").last
+      end
+
+      private
+
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+end

data/lib/ask/decision_result.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Ask
+  # Typed answer objects returned by a DecisionProvider. Each answer type
+  # carries the raw values plus convenience helpers for common patterns.
+  #
+  # @example Reading a Choice answer
+  #   result = Ask.decide(state: "...", decisions: { "route" => choice_q })
+  #   result["route"].choice        # => "technical"
+  #   result["route"].confidence   # => 0.84
+  #   result["route"].ranked       # => [["technical", 0.84], ["billing", 0.12], ...]
+  #   result["route"].confident?(0.7)  # => true
+  #
+  module DecisionResult
+    # A single answer from a decision call.
+    module Answer
+      # @return [String] the question id
+      attr_reader :id
+
+      # @return [Float] raw latency of this answer in seconds (set by provider)
+      attr_reader :latency
+
+      def initialize(id:, latency: nil)
+        @id = id
+        @latency = latency
+      end
+    end
+
+    # Choice answer: the picked option, full probability distribution, and confidence.
+    class ChoiceAnswer
+      include Answer
+
+      attr_reader :choice, :probabilities, :confidence, :ranked
+
+      def initialize(id:, choice:, probabilities:, confidence: nil, latency: nil)
+        super(id: id, latency: latency)
+        @choice = choice
+        @probabilities = probabilities.freeze
+        @confidence = confidence
+        @ranked = probabilities.sort_by { |_, v| -v }.freeze
+        freeze
+      end
+
+      def type = :choice
+
+      # The option with the highest probability.
+      def best = ranked.first
+
+      # Whether the confidence meets a threshold. For Choice answers this uses
+      # the calibrated confidence value.
+      def confident?(threshold = 0.7)
+        return false if confidence.nil?
+        confidence >= threshold
+      end
+    end
+
+    # Score answer: a probability-weighted position across your levels.
+    class ScoreAnswer
+      include Answer
+
+      attr_reader :score, :legend, :probabilities, :confidence, :ranked
+
+      def initialize(id:, score:, legend:, probabilities:, confidence: nil, latency: nil)
+        super(id: id, latency: latency)
+        @score = score
+        @legend = legend.freeze
+        @probabilities = probabilities.freeze
+        @confidence = confidence
+        @ranked = probabilities.sort_by { |_, v| -v }.freeze
+        freeze
+      end
+
+      def type = :score
+
+      def best = ranked.first
+
+      def confident?(threshold = 0.7)
+        return false if confidence.nil?
+        confidence >= threshold
+      end
+
+      # The probability-weighted expectation across levels (same as .score).
+      def expected = score
+    end
+
+    # Noul answer: the probability that the statement is true (0–1).
+    # Noul answers do NOT carry a separate confidence value.
+    class NoulAnswer
+      include Answer
+
+      attr_reader :noul
+
+      def initialize(id:, noul:, latency: nil)
+        super(id: id, latency: latency)
+        @noul = noul
+        freeze
+      end
+
+      def type = :noul
+
+      # Noul has no confidence field, so confidence-gating uses the value's
+      # distance from 0.5. Returns the distance; 0 means fully uncertain,
+      # 0.5 means fully certain.
+      def strength
+        (noul - 0.5).abs
+      end
+
+      # Gate a noul answer against a threshold. A noul > 0.5 is a "yes",
+      # and this method checks both the direction and the strength.
+      #
+      # @param threshold [Float] minimum strength (distance from 0.5) to pass
+      # @return [Boolean]
+      def confident?(threshold = 0.3)
+        strength >= threshold
+      end
+
+      def yes?  = noul >= 0.5
+      def no?   = noul < 0.5
+    end
+
+    # Aggregate result from a batch of decisions. Answers are accessed by id.
+    class Batch
+      include Enumerable
+
+      attr_reader :answers, :usage, :model, :latency, :min_confidence
+
+      def initialize(answers:, model: nil, usage: nil, latency: nil)
+        @answers = answers.freeze
+        @model = model
+        @usage = usage
+        @latency = latency
+        @min_confidence = @answers.values
+          .select { |a| a.respond_to?(:confidence) && !a.confidence.nil? }
+          .map(&:confidence)
+          .min
+        freeze
+      end
+
+      # Access an answer by id.
+      def [](id)
+        @answers[id.to_s]
+      end
+
+      def each(&block)
+        @answers.each_value(&block)
+      end
+
+      # Whether every choice/score answer meets a confidence threshold.
+      def all_confident?(threshold = 0.7)
+        return true if @answers.empty?
+        @answers.values.all? do |a|
+          !a.respond_to?(:confidence) || a.confidence.nil? || a.confidence >= threshold
+        end
+      end
+
+      def to_h
+        @answers.transform_values { |a| a.respond_to?(:to_h) ? a.to_h : a }
+      end
+    end
+  end
+end

data/lib/ask/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ask
-  VERSION = "0.11.4"
+  VERSION = "0.12.0"
 end

data/lib/ask.rb

@@ -30,3 +30,6 @@ require_relative "ask/models"
 require_relative "ask/document"
 require_relative "ask/state"
 require_relative "ask/provider_tool"
+require_relative "ask/decision"
+require_relative "ask/decision_result"
+require_relative "ask/decision_provider"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-core
 version: !ruby/object:Gem::Version
-  version: 0.11.4
+  version: 0.12.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -82,6 +82,9 @@ files:
 - lib/ask/content.rb
 - lib/ask/conversation.rb
 - lib/ask/data_uri.rb
+- lib/ask/decision.rb
+- lib/ask/decision_provider.rb
+- lib/ask/decision_result.rb
 - lib/ask/document.rb
 - lib/ask/errors.rb
 - lib/ask/mime.rb