sqa-bi 0.1.0

data/lib/sqa/bi/time_series_predictor.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module SQA
+  module BI
+    # Main interface for Bayesian time series prediction
+    #
+    # TimeSeriesPredictor combines Prior, Likelihood, and Posterior to provide
+    # a simple API for predicting probability distributions over discrete outcomes
+    # given time series features.
+    #
+    # @example Basic usage
+    #   predictor = TimeSeriesPredictor.new(
+    #     outcomes: [-2, -1, 0, 1, 2],
+    #     bandwidth: 1.0
+    #   )
+    #
+    #   # Train with historical data
+    #   predictor.train([1.0, 2.0, 3.0], outcome: 1)
+    #   predictor.train([1.1, 2.1, 2.9], outcome: 1)
+    #   predictor.train([-1.0, -2.0, 0.5], outcome: -2)
+    #
+    #   # Predict for new data
+    #   posterior = predictor.predict([1.05, 2.05, 3.0])
+    #   puts posterior.summary
+    class TimeSeriesPredictor
+      attr_reader :outcomes, :prior, :likelihood, :feature_dimension, :bandwidth
+
+      # Initialize predictor
+      #
+      # @param outcomes [Array] Discrete outcome values (e.g., [-2, -1, 0, 1, 2])
+      # @param bandwidth [Float] Kernel bandwidth for likelihood estimation
+      # @param prior_probabilities [Hash, nil] Custom prior probabilities
+      #   If nil, uses uniform prior
+      # @param update_prior [Boolean] Whether to update prior from observations
+      #
+      # @example
+      #   predictor = TimeSeriesPredictor.new(
+      #     outcomes: [-2, -1, 0, 1, 2],
+      #     bandwidth: 1.0,
+      #     update_prior: true
+      #   )
+      def initialize(outcomes:, bandwidth: 1.0, prior_probabilities: nil, update_prior: true)
+        @outcomes = outcomes.sort
+        @bandwidth = bandwidth
+        @update_prior = update_prior
+        @feature_dimension = nil
+
+        # Initialize prior
+        @prior = Prior.new(@outcomes, prior_probabilities)
+
+        # Initialize likelihood
+        @likelihood = Likelihood.new([], bandwidth: @bandwidth)
+      end
+
+      # Train predictor with new observation
+      #
+      # @param features [Array<Numeric>] Feature vector (e.g., [x, y, z])
+      # @param outcome [Numeric] Observed outcome
+      # @return [self] For method chaining
+      #
+      # @example
+      #   predictor.train([1.0, 2.0, 3.0], outcome: 1)
+      #   predictor.train([1.1, 2.1, 2.9], outcome: 1)
+      def train(features, outcome:)
+        validate_features!(features)
+        validate_outcome!(outcome)
+
+        @likelihood.add_observation(features, outcome)
+
+        # Update prior based on observed frequencies
+        if @update_prior && @likelihood.size >= @outcomes.size
+          @prior = @prior.update_from_observations(@likelihood.outcome_counts)
+        end
+
+        self
+      end
+
+      # Batch train with multiple observations
+      #
+      # @param observations [Array<Hash>] Array of {features: [...], outcome: ...}
+      # @return [self] For method chaining
+      #
+      # @example
+      #   observations = [
+      #     {features: [1.0, 2.0, 3.0], outcome: 1},
+      #     {features: [1.1, 2.1, 2.9], outcome: 1},
+      #     {features: [-1.0, -2.0, 0.5], outcome: -2}
+      #   ]
+      #   predictor.train_batch(observations)
+      def train_batch(observations)
+        observations.each do |obs|
+          train(obs[:features], outcome: obs[:outcome])
+        end
+        self
+      end
+
+      # Predict posterior distribution for given features
+      #
+      # @param features [Array<Numeric>] Feature vector to predict
+      # @return [Posterior] Posterior probability distribution
+      #
+      # @example
+      #   posterior = predictor.predict([1.0, 2.0, 3.0])
+      #   puts "Most likely outcome: #{posterior.max_outcome}"
+      #   puts "Confidence: #{posterior.confidence}"
+      def predict(features)
+        validate_features!(features)
+
+        # Compute likelihoods for all outcomes
+        likelihoods = @likelihood.compute(features, @outcomes)
+
+        # Compute posterior
+        Posterior.new(@prior, likelihoods)
+      end
+
+      # Predict and return most likely outcome
+      #
+      # @param features [Array<Numeric>] Feature vector
+      # @return [Numeric] Most likely outcome (MAP estimate)
+      def predict_outcome(features)
+        predict(features).max_outcome
+      end
+
+      # Predict probabilities as simple hash
+      #
+      # @param features [Array<Numeric>] Feature vector
+      # @return [Hash] {outcome => probability}
+      def predict_proba(features)
+        predict(features).to_h
+      end
+
+      # Get current number of training observations
+      #
+      # @return [Integer]
+      def training_size
+        @likelihood.size
+      end
+
+      # Check if predictor has been trained
+      #
+      # @return [Boolean]
+      def trained?
+        !@likelihood.empty?
+      end
+
+      # Get distribution of outcomes in training data
+      #
+      # @return [Hash] {outcome => count}
+      def training_distribution
+        @likelihood.outcome_counts
+      end
+
+      # Reset predictor to initial state
+      #
+      # @param keep_prior [Boolean] Whether to keep the current prior
+      # @return [self]
+      def reset!(keep_prior: false)
+        @prior = Prior.new(@outcomes) unless keep_prior
+        @likelihood = Likelihood.new([], bandwidth: @bandwidth)
+        @feature_dimension = nil
+        self
+      end
+
+      # Update kernel bandwidth for likelihood estimation
+      #
+      # @param new_bandwidth [Float] New bandwidth value
+      # @return [self]
+      def bandwidth=(new_bandwidth)
+        @bandwidth = new_bandwidth
+        # Recreate likelihood with new bandwidth
+        @likelihood = Likelihood.new(@likelihood.observations, bandwidth: @bandwidth)
+        self
+      end
+
+      # Get summary statistics
+      #
+      # @return [String] Formatted summary
+      def summary
+        <<~SUMMARY
+          TimeSeriesPredictor Summary:
+          =============================
+          Outcomes: #{@outcomes.inspect}
+          Feature Dimension: #{@feature_dimension || 'not set'}
+          Training Samples: #{training_size}
+          Bandwidth: #{@bandwidth}
+          Update Prior: #{@update_prior}
+
+          Prior Distribution:
+          #{@prior}
+          Prior Entropy: #{format('%.3f', @prior.entropy)} bits
+
+          Training Distribution:
+          #{training_distribution.map { |outcome, count| "  #{outcome}: #{count}" }.join("\n")}
+        SUMMARY
+      end
+
+      private
+
+      def validate_features!(features)
+        unless features.is_a?(Array) && features.all?(Numeric)
+          raise ArgumentError, "Features must be array of numbers"
+        end
+
+        dimension = features.size
+
+        if @feature_dimension.nil?
+          @feature_dimension = dimension
+        elsif dimension != @feature_dimension
+          raise ArgumentError, "Feature dimension mismatch: expected #{@feature_dimension}, got #{dimension}"
+        end
+      end
+
+      def validate_outcome!(outcome)
+        return if @outcomes.include?(outcome)
+        raise ArgumentError, "Invalid outcome: #{outcome}. Must be one of #{@outcomes}"
+      end
+    end
+  end
+end

data/lib/sqa/bi/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SQA
+  module BI
+    VERSION = "0.1.0"
+  end
+end

data/lib/sqa/bi.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "bi/version"
+require_relative "bi/prior"
+require_relative "bi/likelihood"
+require_relative "bi/posterior"
+require_relative "bi/time_series_predictor"
+require_relative "bi/llm_support"
+require_relative "bi/llm_prior_elicitor"
+require_relative "bi/llm_likelihood_estimator"
+
+module SQA
+  # Bayesian inference over discrete outcomes from time series data.
+  #
+  # SQA::BI answers questions of the form "given these features, what is
+  # the probability distribution over outcomes?" — where the outcomes are
+  # a small ordered set such as [-2, -1, 0, 1, 2] (strong downtrend
+  # through strong uptrend). It provides:
+  #
+  # - Prior distributions with Laplace smoothing
+  # - Gaussian kernel density estimation for likelihoods
+  # - Bayesian posterior computation, with entropy, confidence,
+  #   KL divergence from the prior, and sampling
+  # - An LLM as an optional prior elicitor or likelihood function over
+  #   textual evidence, where Ruby still does all the arithmetic
+  #
+  # The core math is domain-agnostic — it knows nothing about markets.
+  # This gem therefore does not depend on the +sqa+ gem; see
+  # +examples/03_stock_market_prediction_v2.rb+ for the market-facing
+  # side, which bridges SQA::DataFrame into a feature vector.
+  #
+  # @example Basic usage
+  #   include SQA::BI
+  #
+  #   predictor = TimeSeriesPredictor.new(
+  #     outcomes: [-2, -1, 0, 1, 2],
+  #     bandwidth: 1.0
+  #   )
+  #
+  #   predictor.train([1.0, 2.0, 3.0], outcome: 1)
+  #   predictor.train([1.1, 2.1, 2.9], outcome: 1)
+  #
+  #   posterior = predictor.predict([1.05, 2.05, 3.0])
+  #   puts posterior.summary
+  module BI
+    class Error < StandardError; end
+
+    # Convenience constructor for a predictor.
+    #
+    # @param outcomes [Array] discrete outcomes
+    # @param bandwidth [Float] kernel bandwidth
+    # @return [TimeSeriesPredictor]
+    def self.predictor(outcomes:, bandwidth: 1.0, **)
+      TimeSeriesPredictor.new(outcomes: outcomes, bandwidth: bandwidth, **)
+    end
+  end
+end

data/mkdocs.yml

@@ -0,0 +1,174 @@
+# MkDocs configuration for SQA::BI documentation
+site_name: SQA::BI — Bayesian Inference
+site_description: Bayesian inference over discrete outcomes from time series data
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/sqa-bi
+copyright: Copyright © 2026 Dewayne VanHoozer
+
+# Repository information
+repo_name: madbomber/sqa-bi
+repo_url: https://github.com/MadBomber/sqa-bi
+edit_uri: edit/main/docs/
+
+# Configuration
+theme:
+  name: material
+
+  # Color scheme - default to dark mode
+  palette:
+    # Palette toggle for dark mode (default)
+    - scheme: slate
+      primary: indigo
+      accent: cyan
+      toggle:
+        icon: material/brightness-7
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - scheme: default
+      primary: indigo
+      accent: cyan
+      toggle:
+        icon: material/brightness-4
+        name: Switch to dark mode
+
+  # Typography
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  # Theme features
+  features:
+    # Navigation
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+
+    # Table of contents
+    - toc.follow
+
+    # Search
+    - search.suggest
+    - search.highlight
+    - search.share
+
+    # Header
+    - header.autohide
+
+    # Content
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+# Link and reference validation. With --strict these become build errors,
+# which is what keeps the cross-references in this site honest.
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+  anchors: warn
+
+# Plugins
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+
+# Extensions
+markdown_extensions:
+  # Python Markdown
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+
+  # Python Markdown Extensions
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: madbomber
+      repo: sqa-bi
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+# Extra CSS and JavaScript
+extra_css:
+  - assets/css/custom.css
+
+extra_javascript:
+  - assets/js/mathjax.js
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
+# Social media and extra configuration
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/madbomber/sqa-bi
+      name: SQA::BI on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/sqa-bi
+      name: SQA::BI on RubyGems
+
+# Navigation
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Installation: getting-started/installation.md
+    - Quick Start: getting-started/quick-start.md
+    - Core Concepts: getting-started/core-concepts.md
+  - Guide:
+    - The Prior: guide/prior.md
+    - The Likelihood: guide/likelihood.md
+    - The Posterior: guide/posterior.md
+    - The Predictor: guide/predictor.md
+    - Quantifying Uncertainty: guide/uncertainty.md
+    - Tuning and Modeling Choices: guide/tuning.md
+  - LLM Integration:
+    - Overview: llm/index.md
+    - Prior Elicitation: llm/prior-elicitation.md
+    - Likelihood Estimation: llm/likelihood-estimation.md
+    - Providers and Local Models: llm/providers.md
+  - API Reference:
+    - Overview: api/index.md
+    - SQA::BI::Prior: api/prior.md
+    - SQA::BI::Likelihood: api/likelihood.md
+    - SQA::BI::Posterior: api/posterior.md
+    - SQA::BI::TimeSeriesPredictor: api/time-series-predictor.md
+    - SQA::BI::LlmSupport: api/llm-support.md
+    - LLM Elicitors: api/llm-elicitors.md
+  - Examples: examples/index.md
+  - Development: development.md
+  - Exploration Notes: EXPLORATION.md