sqa-bi 0.1.0

data/lib/sqa/bi/llm_support.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module SQA
+  module BI
+    # Shared plumbing for classes that get numbers out of an LLM.
+    #
+    # LLMs return prose; Bayes' theorem needs clean numeric hashes. Every
+    # method here is a module_function so it can be tested in isolation
+    # without instantiating anything.
+    #
+    # Provider strategy — local first:
+    #   1. SQA_BI_LLM_PROVIDER env var (lms | apfel | cloud) if set
+    #   2. LM Studio via ruby_llm-providers-lms   (http://localhost:1234/v1)
+    #   3. Apfel (Apple Foundation Models) via ruby_llm-providers-apfel
+    #      (http://127.0.0.1:11434/v1)
+    #   4. cloud fallback through the plain ruby_llm registry
+    # SQA_BI_LLM_MODEL overrides the model in every case.
+    #
+    # The unprefixed BI_LLM_PROVIDER / BI_LLM_MODEL names this library
+    # used before it moved into the SQA workspace are still honored as a
+    # fallback, so existing shell setups keep working.
+    module LlmSupport
+      module_function
+
+      LMS_DEFAULT_BASE   = 'http://localhost:1234/v1'
+      APFEL_DEFAULT_BASE = 'http://127.0.0.1:11434/v1'
+      CLOUD_DEFAULT_MODEL = 'claude-haiku-4-5'
+
+      def lms_api_base
+        ENV.fetch('LMS_API_BASE', LMS_DEFAULT_BASE)
+      end
+
+      def apfel_api_base
+        ENV.fetch('APFEL_API_BASE', APFEL_DEFAULT_BASE)
+      end
+
+      # Read the first non-blank value among a list of env var names.
+      #
+      # @param names [Array<String>]
+      # @return [String, nil]
+      def env_value(*names)
+        names.each do |name|
+          value = ENV[name]&.strip
+          return value unless value.nil? || value.empty?
+        end
+        nil
+      end
+
+      # Model override from the environment, nil when unset/blank.
+      def env_model
+        env_value('SQA_BI_LLM_MODEL', 'BI_LLM_MODEL')
+      end
+
+      # Which provider to talk to: explicit env choice, else the first
+      # local server that answers, else the cloud.
+      #
+      # @return [Symbol] :lms, :apfel, or :cloud
+      def resolve_provider
+        env = env_value('SQA_BI_LLM_PROVIDER', 'BI_LLM_PROVIDER')
+        return env.to_sym if env
+        return :lms if server_alive?(lms_api_base)
+        return :apfel if server_alive?(apfel_api_base)
+
+        :cloud
+      end
+
+      # Quick liveness probe against an OpenAI-compatible /models endpoint.
+      #
+      # @param base [String] API base URL (".../v1")
+      # @return [Boolean]
+      def server_alive?(base, timeout: 1)
+        uri = URI("#{base}/models")
+        Net::HTTP.start(uri.host, uri.port, open_timeout: timeout, read_timeout: timeout) do |http|
+          http.get(uri.path).code.start_with?('2')
+        end
+      rescue StandardError
+        false
+      end
+
+      # Model ids served right now by a local OpenAI-compatible server.
+      #
+      # @param base [String] API base URL (".../v1")
+      # @return [Array<String>]
+      def list_local_models(base)
+        uri = URI("#{base}/models")
+        body = Net::HTTP.get(uri)
+        JSON.parse(body).fetch('data', []).map { |m| m['id'] }
+      rescue StandardError
+        []
+      end
+
+      # Pick the best judgment model from a local server's offerings.
+      # Qwen models honor JSON/structured prompts most reliably in LM
+      # Studio (see ruby_llm-providers-lms README), then gpt-oss; embedding
+      # and OCR models are never eligible.
+      #
+      # @param ids [Array<String>] model ids as listed by the server
+      # @return [String, nil]
+      def choose_local_model(ids)
+        chat_ids = ids.grep_v(/embed|ocr/i)
+        chat_ids.find { |id| id.match?(/qwen/i) } ||
+          chat_ids.find { |id| id.match?(/gpt-oss/i) } ||
+          chat_ids.first
+      end
+
+      # Build a lazily-required RubyLLM chat so the core math library
+      # never depends on ruby_llm being installed.
+      #
+      # @param model [String, nil] model id; nil resolves per provider
+      # @param provider [Symbol, String, nil] :lms, :apfel, :cloud;
+      #   nil auto-detects via resolve_provider
+      # @return [RubyLLM::Chat]
+      def build_chat(model = nil, provider: nil)
+        require_ruby_llm
+        configure_ruby_llm
+        provider = (provider || resolve_provider).to_sym
+        model ||= env_model
+        base = local_api_base(provider)
+
+        if base
+          local_chat(provider, model, base)
+        else
+          RubyLLM.chat(model: model || CLOUD_DEFAULT_MODEL)
+        end
+      end
+
+      # API base for a local provider, or nil when the provider is a
+      # cloud one.
+      #
+      # @param provider [Symbol] :lms, :apfel, or :cloud
+      # @return [String, nil]
+      def local_api_base(provider)
+        case provider
+        when :lms   then lms_api_base
+        when :apfel then apfel_api_base
+        end
+      end
+
+      # One-line description of where a chat would be sent.
+      #
+      # Local-first resolution is silent by design, which means a dead or
+      # stopped LM Studio server looks identical to a deliberate cloud
+      # run until a provider error surfaces. Callers that care — the demo
+      # apps do — can show this first.
+      #
+      # @param provider [Symbol] :lms, :apfel, or :cloud
+      # @param model [String, nil] resolved model id
+      # @param base [String, nil] local server base; nil for cloud
+      # @return [String]
+      def resolution_label(provider, model, base)
+        target = model || '(no chat model available)'
+        base ? "#{provider} — #{target} at #{base}" : "#{provider} — #{target}"
+      end
+
+      # Where the next chat built with these arguments will actually go.
+      # Probes the local servers, so it costs one HTTP round trip.
+      #
+      # @param model [String, nil] explicit model id, if any
+      # @param provider [Symbol, nil] explicit provider, if any
+      # @return [String] as formatted by resolution_label
+      def current_resolution(model = nil, provider: nil)
+        provider = (provider || resolve_provider).to_sym
+        base = local_api_base(provider)
+        model ||= env_model
+        model ||= base ? choose_local_model(list_local_models(base)) : CLOUD_DEFAULT_MODEL
+
+        resolution_label(provider, model, base)
+      end
+
+      # Require ruby_llm, turning both failure modes into one actionable
+      # message. It is an optional dependency, so it may simply be absent;
+      # and when the process is running outside the bundle, RubyGems can
+      # activate a gem version ruby_llm rejects (json >= 3) long before
+      # this require runs. The latter surfaces as Gem::ConflictError, which
+      # is itself a LoadError, so one rescue covers both.
+      #
+      # @raise [SQA::BI::Error] when ruby_llm cannot be loaded
+      def require_ruby_llm
+        require 'ruby_llm'
+      rescue LoadError => e
+        raise Error, <<~MESSAGE
+          Could not load ruby_llm (#{e.class}: #{e.message}).
+
+          ruby_llm is an optional dependency of sqa-bi — only the LLM-backed
+          prior and likelihood paths need it; the KDE path does not.
+
+          If it is installed, this usually means the process is running
+          outside the bundle. Run it with `bundle exec`, or let direnv set
+          BUNDLE_GEMFILE (`asgard dev` / `asgard prod` at the workspace root).
+        MESSAGE
+      end
+
+      # @param provider [Symbol] :lms or :apfel
+      # @param model [String, nil]
+      # @param base [String] server API base, used to pick a model when none given
+      # @return [RubyLLM::Chat]
+      def local_chat(provider, model, base)
+        model ||= choose_local_model(list_local_models(base))
+        raise Error, "No chat model available from #{provider} server at #{base}" unless model
+
+        RubyLLM.chat(model:, provider:, assume_model_exists: true)
+      end
+
+      # Register the local provider gems and point RubyLLM at whichever
+      # cloud keys exist in the environment. Runs once; safe to call
+      # repeatedly.
+      def configure_ruby_llm
+        return if @ruby_llm_configured
+
+        require_local_providers
+
+        RubyLLM.configure do |config|
+          config.anthropic_api_key = ENV['ANTHROPIC_API_KEY'] if ENV['ANTHROPIC_API_KEY']
+          config.openai_api_key    = ENV['OPENAI_API_KEY']    if ENV['OPENAI_API_KEY']
+          config.gemini_api_key    = ENV['GEMINI_API_KEY']    if ENV['GEMINI_API_KEY']
+          config.lms_api_base      = lms_api_base   if config.respond_to?(:lms_api_base=)
+          config.apfel_api_base    = apfel_api_base if config.respond_to?(:apfel_api_base=)
+        end
+        @ruby_llm_configured = true
+      end
+
+      # The provider gems are optional: their absence only disables the
+      # corresponding provider, it never breaks the cloud path.
+      def require_local_providers
+        %w[ruby_llm/providers/lms ruby_llm/providers/apfel].each do |path|
+          require path
+        rescue LoadError
+          nil
+        end
+      end
+
+      # Pull a Hash out of whatever the LLM returned.
+      #
+      # Accepts an already-parsed Hash (e.g., from structured output or a
+      # test double), a raw JSON string, or prose containing a JSON object
+      # (possibly inside a ```json fence).
+      #
+      # @param content [Hash, String, #to_s] LLM response content
+      # @return [Hash] parsed JSON object with string keys
+      # @raise [SQA::BI::Error] when no JSON object can be found
+      def extract_json(content)
+        return content if content.is_a?(Hash)
+
+        text = content.to_s
+        json = text[/\{.*\}/m]
+        raise Error, "No JSON object found in LLM response: #{text.inspect}" unless json
+
+        JSON.parse(json)
+      rescue JSON::ParserError => e
+        raise Error, "Malformed JSON from LLM: #{e.message}"
+      end
+
+      # Re-key an LLM-produced hash onto the caller's outcome objects.
+      #
+      # JSON keys are always strings; outcomes may be integers, symbols,
+      # or strings. Matches on +to_s+ equality. Missing outcomes get 0.0.
+      #
+      # @param raw [Hash] {string_key => Numeric}
+      # @param outcomes [Array] the caller's outcome objects
+      # @return [Hash] {outcome => Float}
+      def rekey_to_outcomes(raw, outcomes)
+        by_string = raw.transform_keys(&:to_s)
+        outcomes.to_h do |outcome|
+          [outcome, by_string.fetch(outcome.to_s, 0.0).to_f]
+        end
+      end
+
+      # Normalize weights into a proper probability distribution.
+      #
+      # Adds a small epsilon before normalizing so no outcome is ever
+      # assigned exactly zero probability — a zero prior can never recover
+      # no matter how much evidence arrives (Cromwell's rule).
+      #
+      # @param weights [Hash] {outcome => non-negative Numeric}
+      # @param epsilon [Float] floor added to every weight
+      # @return [Hash] {outcome => Float} summing to 1.0
+      def normalize_distribution(weights, epsilon: 1e-6)
+        floored = weights.transform_values { |weight| [weight.to_f, 0.0].max + epsilon }
+        total = floored.values.sum
+        floored.transform_values { |weight| weight / total }
+      end
+
+      # Clamp a likelihood into an open unit interval.
+      #
+      # Keeps LLM overconfidence (0.0 / 1.0 answers) from zeroing out or
+      # saturating the posterior in a single update.
+      #
+      # @param value [Numeric]
+      # @return [Float] value clamped to [floor, ceiling]
+      def clamp_likelihood(value, floor: 0.001, ceiling: 0.999)
+        value.to_f.clamp(floor, ceiling)
+      end
+    end
+  end
+end

data/lib/sqa/bi/posterior.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module SQA
+  module BI
+    # Computes posterior probability distribution using Bayes' theorem
+    #
+    # Bayes' Theorem: P(outcome | data) ∝ P(data | outcome) × P(outcome)
+    #
+    # The Posterior class combines prior beliefs and observed data likelihoods
+    # to produce an updated probability distribution over outcomes.
+    class Posterior
+      attr_reader :prior, :likelihoods, :probabilities
+
+      # Initialize posterior distribution
+      #
+      # @param prior [Prior] Prior probability distribution
+      # @param likelihoods [Hash] Likelihood values {outcome => P(data|outcome)}
+      #
+      # @example
+      #   prior = Prior.new([-2, -1, 0, 1, 2])
+      #   likelihoods = {-2 => 0.05, -1 => 0.1, 0 => 0.15, 1 => 0.6, 2 => 0.1}
+      #   posterior = Posterior.new(prior, likelihoods)
+      def initialize(prior, likelihoods)
+        @prior = prior
+        @likelihoods = likelihoods
+        @probabilities = compute_posterior
+      end
+
+      # Get posterior probability for specific outcome
+      #
+      # @param outcome [Numeric] The outcome to query
+      # @return [Float] Posterior probability
+      def probability(outcome)
+        @probabilities[outcome] || 0.0
+      end
+      alias [] probability
+
+      # Get the most likely outcome (MAP estimate)
+      #
+      # @return [Numeric] Outcome with highest posterior probability
+      def max_outcome
+        @probabilities.max_by { |_outcome, prob| prob }&.first
+      end
+
+      # Get top N most likely outcomes
+      #
+      # @param n [Integer] Number of outcomes to return
+      # @return [Array<Array>] Array of [outcome, probability] sorted by probability
+      #
+      # @example
+      #   posterior.top_outcomes(3)
+      #   # => [[1, 0.6], [0, 0.15], [-1, 0.1]]
+      def top_outcomes(n = 3)
+        @probabilities.sort_by { |_outcome, prob| -prob }.take(n)
+      end
+
+      # Get probability distribution as sorted array
+      #
+      # @return [Array<Array>] Array of [outcome, probability] sorted by outcome
+      def to_a
+        @probabilities.sort_by { |outcome, _prob| outcome }
+      end
+
+      # Get probability distribution as hash
+      #
+      # @return [Hash] {outcome => probability}
+      def to_h
+        @probabilities.dup
+      end
+
+      # Compute entropy of posterior distribution
+      # Higher entropy = more uncertain, Lower entropy = more confident
+      #
+      # @return [Float] Shannon entropy in bits
+      def entropy
+        -@probabilities.values.reduce(0.0) do |sum, prob|
+          sum + (prob.positive? ? prob * Math.log2(prob) : 0)
+        end
+      end
+
+      # Compute Kullback-Leibler divergence from prior to posterior
+      # Measures information gain from observing data
+      #
+      # @return [Float] KL divergence in bits (always non-negative)
+      def kl_divergence_from_prior
+        @probabilities.reduce(0.0) do |sum, (outcome, posterior_prob)|
+          prior_prob = @prior.probability(outcome)
+          if posterior_prob.positive? && prior_prob.positive?
+            sum + (posterior_prob * Math.log2(posterior_prob / prior_prob))
+          else
+            sum
+          end
+        end
+      end
+
+      # Get confidence level (1 - entropy / max_entropy)
+      # Returns value between 0 (uniform, no confidence) and 1 (certain)
+      #
+      # @return [Float] Confidence level
+      def confidence
+        max_entropy = Math.log2(@probabilities.size)
+        1.0 - (entropy / max_entropy)
+      end
+
+      # Sample an outcome from the posterior distribution
+      #
+      # @param rng [Random] Random number generator
+      # @return [Numeric] Sampled outcome
+      def sample(rng: Random.new)
+        cumulative = 0.0
+        threshold = rng.rand
+
+        @probabilities.each do |outcome, prob|
+          cumulative += prob
+          return outcome if cumulative >= threshold
+        end
+
+        # Fallback (shouldn't reach here if probabilities sum to 1)
+        @probabilities.keys.last
+      end
+
+      # Generate N samples from the posterior distribution
+      #
+      # @param n [Integer] Number of samples
+      # @param rng [Random] Random number generator
+      # @return [Array] Array of sampled outcomes
+      def samples(n, rng: Random.new)
+        Array.new(n) { sample(rng: rng) }
+      end
+
+      # Return formatted string representation
+      #
+      # @return [String] Formatted probability distribution
+      def to_s
+        parts = @probabilities.sort.map do |outcome, prob|
+          "#{outcome}: #{format('%.3f', prob)}"
+        end
+        "Posterior(#{parts.join(', ')})"
+      end
+
+      # Return detailed summary with statistics
+      #
+      # @return [String] Multi-line summary
+      def summary
+        max_out = max_outcome
+        max_prob = probability(max_out)
+
+        <<~SUMMARY
+          Posterior Distribution Summary:
+          ================================
+          Most Likely: #{max_out} (#{format('%.1f%%', max_prob * 100)})
+          Confidence: #{format('%.1f%%', confidence * 100)}
+          Entropy: #{format('%.3f', entropy)} bits
+          KL Divergence from Prior: #{format('%.3f', kl_divergence_from_prior)} bits
+
+          Probabilities:
+          #{to_a.map { |outcome, prob| "  #{outcome}: #{format('%.3f', prob)} (#{format('%.1f%%', prob * 100)})" }.join("\n")}
+        SUMMARY
+      end
+
+      private
+
+      # Compute posterior using Bayes' theorem
+      # P(outcome | data) = P(data | outcome) × P(outcome) / P(data)
+      #
+      # @return [Hash] Normalized posterior probabilities
+      def compute_posterior
+        # Compute unnormalized posterior: likelihood × prior
+        unnormalized = @prior.outcomes.each_with_object({}) do |outcome, hash|
+          likelihood = @likelihoods[outcome] || 0.0
+          prior_prob = @prior.probability(outcome)
+          hash[outcome] = likelihood * prior_prob
+        end
+
+        # Normalize to sum to 1
+        total = unnormalized.values.sum
+
+        if total.positive?
+          unnormalized.transform_values { |v| v / total }
+        else
+          # All zeros, fall back to prior
+          @prior.outcomes.to_h do |outcome|
+            [outcome, @prior.probability(outcome)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sqa/bi/prior.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module SQA
+  module BI
+    # Manages prior probability distributions over discrete outcomes
+    #
+    # The Prior class represents our initial beliefs about outcome probabilities
+    # before observing any data. It supports:
+    # - Uniform priors (equal probability for all outcomes)
+    # - Custom priors (specified probabilities)
+    # - Dynamic updating based on historical observations
+    class Prior
+      attr_reader :outcomes, :probabilities
+
+      # Initialize a prior distribution
+      #
+      # @param outcomes [Array] Discrete outcomes (e.g., [-2, -1, 0, 1, 2])
+      # @param probabilities [Hash, nil] Optional custom probabilities {outcome => probability}
+      #   If nil, uses uniform distribution
+      #
+      # @example Uniform prior
+      #   prior = Prior.new([-2, -1, 0, 1, 2])
+      #
+      # @example Custom prior favoring neutral outcome
+      #   prior = Prior.new([-2, -1, 0, 1, 2], {-2 => 0.1, -1 => 0.15, 0 => 0.5, 1 => 0.15, 2 => 0.1})
+      def initialize(outcomes, probabilities = nil)
+        @outcomes = outcomes.sort
+
+        if probabilities
+          validate_probabilities!(probabilities)
+          @probabilities = probabilities
+        else
+          # Uniform prior: equal probability for all outcomes
+          uniform_prob = 1.0 / outcomes.size
+          @probabilities = outcomes.to_h do |outcome|
+            [outcome, uniform_prob]
+          end
+        end
+      end
+
+      # Get probability for a specific outcome
+      #
+      # @param outcome [Numeric] The outcome to query
+      # @return [Float] Probability of the outcome
+      def probability(outcome)
+        @probabilities[outcome] || 0.0
+      end
+      alias [] probability
+
+      # Update prior based on observed outcome frequencies
+      #
+      # Uses Laplace smoothing (add-1 smoothing) to avoid zero probabilities
+      #
+      # @param observations [Hash] Observed outcome frequencies {outcome => count}
+      # @param smoothing [Float] Laplace smoothing parameter (default: 1.0)
+      # @return [Prior] New Prior instance with updated probabilities
+      #
+      # @example
+      #   observations = {-2 => 5, -1 => 10, 0 => 20, 1 => 12, 2 => 3}
+      #   updated_prior = prior.update_from_observations(observations)
+      def update_from_observations(observations, smoothing: 1.0)
+        total_count = observations.values.sum
+
+        new_probabilities = @outcomes.each_with_object({}) do |outcome, hash|
+          # Laplace smoothing: (count + smoothing) / (total + smoothing * num_outcomes)
+          count = observations[outcome] || 0
+          hash[outcome] = (count + smoothing) / (total_count + (smoothing * @outcomes.size))
+        end
+
+        self.class.new(@outcomes, new_probabilities)
+      end
+
+      # Combine this prior with another using weighted average
+      #
+      # @param other_prior [Prior] Another prior distribution
+      # @param weight [Float] Weight for this prior (0.0 to 1.0)
+      # @return [Prior] New Prior with combined probabilities
+      def combine(other_prior, weight: 0.5)
+        unless outcomes_compatible?(other_prior)
+          raise ArgumentError, "Cannot combine priors with different outcomes"
+        end
+
+        new_probabilities = @outcomes.to_h do |outcome|
+          [outcome, (weight * probability(outcome)) +
+            ((1 - weight) * other_prior.probability(outcome))]
+        end
+
+        self.class.new(@outcomes, new_probabilities)
+      end
+
+      # Get entropy of the prior distribution
+      # Higher entropy = more uncertain/uniform, Lower entropy = more peaked/certain
+      #
+      # @return [Float] Shannon entropy in bits
+      def entropy
+        -@probabilities.values.reduce(0.0) do |sum, prob|
+          sum + (prob.positive? ? prob * Math.log2(prob) : 0)
+        end
+      end
+
+      # Return a human-readable representation
+      #
+      # @return [String] Formatted probability distribution
+      def to_s
+        parts = @outcomes.map { |outcome| "#{outcome}: #{format('%.3f', probability(outcome))}" }
+        "Prior(#{parts.join(', ')})"
+      end
+
+      private
+
+      def validate_probabilities!(probabilities)
+        # Check all outcomes are present
+        missing = @outcomes - probabilities.keys
+        unless missing.empty?
+          raise ArgumentError, "Missing probabilities for outcomes: #{missing}"
+        end
+
+        # Check probabilities sum to 1.0 (with small tolerance)
+        total = probabilities.values.sum
+        unless (total - 1.0).abs < 1e-6
+          raise ArgumentError, "Probabilities must sum to 1.0, got #{total}"
+        end
+
+        # Check all probabilities are non-negative
+        negative = probabilities.select { |_k, v| v.negative? }
+        return if negative.empty?
+        raise ArgumentError, "Probabilities must be non-negative: #{negative}"
+      end
+
+      def outcomes_compatible?(other_prior)
+        @outcomes == other_prior.outcomes
+      end
+    end
+  end
+end