sqa-bi 0.1.0

data/decision_support_techniques.md

@@ -0,0 +1,391 @@
+# Decision Support Techniques — Log
+
+Running log of investigations into non-LLM (and LLM-adjacent) decision-making
+techniques for the SQA ecosystem. Newest entries at the bottom. Each entry
+records what was asked, what was actually verified (with evidence), what was
+concluded, and what was left open.
+
+---
+
+## 2026-09-20 — Laya (System 1 decision model) evaluation
+
+### Question
+
+Laya is a new kind of model getting attention for decision-making. Does it have
+a place in SQA? Specifically: can it forecast whether a stock's price will rise
+or fall 1–10 days after a historical event, given end-of-day OHLCV plus a set of
+TA indicators — producing a probability distribution of rise/fall across that
+1–10 day horizon?
+
+Sources:
+- https://laya.convaiinnovations.com/
+- https://github.com/NandhaKishorM/laya
+
+Starting assumption (mine): LM Studio is serving 3 Laya models locally, and the
+`ruby_llm` provider gems `lms` and `apfel` would reach them.
+
+### What Laya actually is
+
+Not a generative LLM. A **non-autoregressive bidirectional encoder** on
+ModernBERT-large (421M) or mmBERT-base (322M) backbones, trained with
+reinforcement learning with calibrated decisions (RLCD). Apache 2.0.
+
+- Outputs **typed decisions only**, never text:
+  - `choice` — pick from options; returns key + per-option probabilities
+  - `score` — ordinal scale; returns expected level + distribution
+  - `noul` — boolean question; returns calibrated P(true) 0.0–1.0
+- ~33ms single forward pass (T4 GPU), 7.2ms/question batched
+- All questions answered in one forward pass
+- Calibrated confidence (ships over-confident; temperature fitting moves ECE
+  0.466 → 0.081)
+- Three checkpoints: `laya` (English), `laya-multilingual` (100+ langs),
+  `laya-typed-decisions` (fine-tuned domain tasks)
+- Python SDK only: `laya.load()`, `Router#predict(state, questions)`,
+  `Agent#predict`. Input is text / JSON / structured state.
+
+Explicitly **not OpenAI chat-completion compatible**. There is no standalone
+HTTP server mode — inference lives inside the Python package.
+
+### Finding 1 — the `ruby_llm` provider path does not reach Laya
+
+Read both installed provider gems (v0.2.1 each):
+
+- `ruby_llm-providers-lms` — LM Studio. Covers three protocols on one port:
+  OpenAI (`/v1/chat/completions`, `/v1/responses`, `/v1/embeddings`), Anthropic
+  (`/v1/messages`), and LM Studio native REST (`/api/v0`, `/api/v1`). All of it
+  is **chat completions and embeddings**.
+- `ruby_llm-providers-apfel` — Apple on-device Foundation Model via the `apfel`
+  CLI's OpenAI-compatible server. Same story.
+
+Neither exposes anything resembling a typed-decision primitive, and LM Studio
+has no knowledge of Laya's classification heads. Even with the base encoder
+weights loaded, hitting `/v1/embeddings` gives you raw encoder output with the
+decision heads and calibration skipped entirely — which is the whole point of
+the model. Whatever the "3 laya models in LM Studio" are, the decision logic is
+not reachable through any endpoint LM Studio serves.
+
+### Finding 2 — fine-tuning Laya in Ruby is not viable
+
+Verified against the installed gems:
+
+| Path | Status |
+|---|---|
+| `ruby_llm` + `:lms` / `:apfel` | LM Studio and Apfel are inference servers. No training endpoint exists in any of their protocols. Categorical dead end. |
+| `transformers-rb` 0.2.0 | Model zoo is exactly `auto, bert, deberta_v2, distilbert, mpnet, xlm_roberta, vit`. **No ModernBERT, no mmBERT** — both of Laya's backbones are absent. |
+| `red-candle` 1.8.1 | Inference only — `llm, embedding_model, reranker, ner, vlm, tool`. No autograd/optimizer surface. |
+| `torch-rb` 0.26.0 | **Can genuinely train** — full optimizer suite (`adam, adamw, sgd, rmsprop, adagrad, adadelta, adamax, asgd, rprop`, plus `lr_scheduler`). |
+
+So fine-tuning a plain BERT/DistilBERT in Ruby is real and available. It is
+ModernBERT specifically that is missing. Going that route would mean hand-porting
+ModernBERT (rotary embeddings, alternating local/global attention, GeGLU,
+unpadding) into torch-rb **and** reverse-engineering Laya's decision-head and
+question-templating scheme out of the Python SDK. Weeks of work to reproduce
+something that already exists in Python.
+
+### Finding 3 — the task is tabular, not textual
+
+The decisive point. The features are OHLCV + TA indicators (numeric); the target
+is direction at k = 1…10. That is tabular binary classification × 10 horizons.
+
+Laya is a 421M-parameter **text** encoder. Using it here means serializing floats
+into digit-tokens and asking self-attention to do arithmetic. Its own docs note
+base checkpoints are weak zero-shot on specialized tasks (0.36 accuracy vs 0.46
+random baseline on typed-decisions) and that ordinal scoring is its weakest
+primitive (0.37 on SST-5). A gradient-boosted tree on the same columns should
+beat it, train in seconds on CPU, and predict in microseconds.
+
+Every property that made Laya attractive is reproducible in Ruby:
+
+| Laya property | Ruby equivalent |
+|---|---|
+| `noul` → calibrated P(true) | binary GBDT + Platt/isotonic calibration on a held-out split |
+| calibrated confidence (ECE 0.466 → 0.081 via temp fitting) | same technique, and validatable against our own backtests |
+| all questions in one forward pass, ~33ms | 10 small models, <1ms total |
+| schema-safe, no hallucination | inherent to a classifier |
+| `choice` / `score` primitives | multiclass / ordinal — `rumale` has both |
+
+### Verified Ruby ML stack on this machine
+
+Richer than expected. All already installed:
+
+- `eps` 0.7.0 — **already a `sqa` gemspec dependency**. `Eps::Model#train(data, target:, algorithm: :lightgbm)`, `#predict_probability`, `#evaluate`, `#summary`.
+- `lightgbm` 0.5.0
+- `rumale` 2.2.0 — full suite: `ensemble, linear_model, neural_network, tree, naive_bayes, model_selection, evaluation_measure, preprocessing, pipeline, kernel_machine, nearest_neighbors, decomposition, clustering, manifold, metric_learning, feature_extraction, kernel_approximation`
+- `torch-rb` 0.26.0, `transformers-rb` 0.2.0, `tokenizers` 0.6.4
+- `red-candle` 1.8.1, `informers` 1.3.0, `onnxruntime` 0.11.7
+- `numo-narray` 0.9.2.1 + `numo-linalg` / `numo-openblas` / `numo-optimize`
+- `polars-df` 0.27.1 (already backing `SQA::DataFrame`), `rover-df`, `daru`
+
+The tabular path therefore needs **zero new dependencies, zero Python, zero GPU**.
+
+Relevant existing `sqa` machinery: `ensemble.rb` (majority/weighted/confidence
+voting over strategies), `gp.rb` (genetic programming), `pattern_matcher.rb`,
+`market_regime.rb`, `backtest.rb`, `strategy_generator.rb`.
+
+### Conclusion
+
+> **Partially superseded — see the next entry.** Item 1 below was revised once
+> the existing `bayesian_inference` project came to light. Item 2 still stands,
+> and got sharper.
+
+Split the two concerns.
+
+1. **Price-direction forecasting — pure Ruby, no Laya.** Build on `eps`
+   (LightGBM) + explicit calibration, living in `sqa`. Keep a Laya-style
+   typed-decision API surface (`noul`-shaped calibrated probabilities) because
+   the ergonomics are good, but the engine underneath is a tree ensemble on
+   tabular features.
+
+2. **Laya for the text side — genuinely worth a POC, later.** `sqa-advisor`
+   currently spends LLM calls on work Laya is purpose-built for: triaging news
+   headlines, classifying filing/earnings-call sentiment, routing which of its
+   14 tools to run, guardrailing inputs. 33ms vs 500–2000ms per decision,
+   calibrated, hallucination-free. That POC needs a small Python sidecar
+   wrapping `Router`/`Agent` (stdlib `http.server` is enough) plus a thin
+   `Net::HTTP` Ruby client — **not** `ruby_llm`, since Laya is not chat-shaped.
+
+### Open / next
+
+- Proposed but not yet built: Ruby forecaster POC — feature builder off
+  `SQA::DataFrame` (OHLCV + selected TAI indicators), 10 calibrated horizon
+  models, and a `RiseFallForecast` value object rendering the 1–10 day
+  rise/fall probability distribution. Awaiting go-ahead.
+- Undecided: exact indicator set for the feature vector.
+- Undecided: whether historical event/outcome pairs come from live Alpha Vantage
+  pulls or a cached local dataset.
+- Not started: the `sqa-advisor` Laya text-decision sidecar POC.
+
+---
+
+## 2026-09-20 (follow-up) — The Bayesian thread was the real one
+
+### Trigger
+
+Noted mid-conversation: separate ongoing work on Bayesian inference, with a
+suspicion that the JEV/Laya excitement had gotten tangled up in it.
+
+It had — but the tangle was informative rather than a mistake, and it changes
+the conclusion above.
+
+### Discovery — the engine already exists
+
+`~/sandbox/git_repos/madbomber/experiments/ai_misc/bayesian_inference/` already
+implements most of what the entry above proposed building from scratch.
+
+From its README and source layout:
+
+- **Purpose**: Bayesian inference over *discrete outcomes* from time series —
+  exactly the problem shape in question.
+- **Outcomes**: `[-2, -1, 0, 1, 2]`, labeled strong downtrend / mild downtrend /
+  … / strong uptrend. That is the rise-fall question, already modeled as an
+  **ordinal** outcome.
+- **Method**: priors (uniform or custom, auto-updating from observations),
+  Gaussian **kernel density estimation** for likelihoods, full posterior via
+  Bayes' theorem.
+- **Uncertainty**: entropy, confidence scores, sampling from the posterior —
+  native, not bolted on.
+- **Library**: `prior.rb`, `likelihood.rb`, `posterior.rb`,
+  `time_series_predictor.rb`, `llm_prior_elicitor.rb`,
+  `llm_likelihood_estimator.rb`, `llm_support.rb`.
+- **Examples**: `02_time_series_prediction.rb`,
+  `03_stock_market_prediction_v2.rb`, `04_llm_elicited_prior.rb`,
+  `05_llm_likelihood_diagnosis.rb`, plus `sqa_polars_compat.rb` (already
+  bridging to `SQA::DataFrame`) and `pure_ruby_indicators.rb`.
+- **LLM integration**: providers auto-detected **local-first** — LM Studio
+  (`ruby_llm-providers-lms`), then Apfel (`ruby_llm-providers-apfel`), then
+  cloud. Overridable via `BI_LLM_PROVIDER` / `BI_LLM_MODEL`. This is the actual
+  origin of the `lms` / `apfel` thread in the original question.
+
+### Why Laya pattern-matched so strongly
+
+Because Laya emits **the same output shape this project already produces**.
+
+| Laya primitive | Equivalent here |
+|---|---|
+| `score` — expected ordinal level + distribution over ranks | `outcomes: [-2,-1,0,1,2]` with a posterior over them |
+| `noul` — calibrated P(true) | posterior probability of a binary outcome |
+| calibrated confidence, no hallucination, typed decisions | entropy / confidence from the posterior, by construction |
+
+Laya's entire pitch is a description of this gem's architecture. The difference
+is only in *how the mapping is learned*: Laya learns it from text via RLCD; this
+learns it from historical numeric data via KDE + Bayes. For OHLCV + TA indicator
+features, the latter is the right mechanism — no text serialization required.
+
+### Revision to the previous entry
+
+The earlier recommendation — build a new `eps`/LightGBM forecaster with Platt
+calibration inside `sqa` — is a step sideways given what already exists. The
+Bayesian predictor is better suited on three counts:
+
+1. It yields a **full posterior**, not a point probability — uncertainty about
+   the uncertainty.
+2. It handles the **ordinal structure natively**. Ten independent binary GBDTs
+   would discard both the ordinal ordering and the strong correlation between
+   adjacent horizons (P(rise at day 3) and P(rise at day 4) are not independent).
+3. Calibration and confidence are intrinsic rather than post-hoc.
+
+`eps` / LightGBM keeps a role as a **benchmark** to score the posterior against,
+not as the primary engine.
+
+### Where the two threads actually converge
+
+At `llm_likelihood_estimator.rb` — and this is the genuinely interesting result.
+
+That file currently uses an LLM as a likelihood function over textual evidence:
+500–2000ms per call, with no calibration guarantee. Laya does exactly that job
+in ~33ms, calibrated, hallucination-free, with typed output. The dispatch seam
+already exists (`llm_support.rb`, provider auto-detection).
+
+**Laya as a fast calibrated likelihood over text (news, filings, earnings calls),
+feeding a Bayesian posterior over price direction.** The Python sidecar is still
+required, since Laya inference lives only in the Python package — but it plugs
+into an architecture that is already built, rather than replacing it.
+
+This also subsumes the `sqa-advisor` idea from the previous entry: same sidecar,
+same client, two consumers.
+
+### On JEV
+
+Unresolved. The only encounter so far is as a benchmark baseline inside Laya's
+own README: Laya 0.766 vs Jev 0.727 on typed-decisions, with Jev reportedly
+stronger on high-cardinality choices (50+ options). No independent knowledge of
+it; deliberately not guessed at. Worth proper research before it influences any
+design decision here.
+
+### Revised open / next
+
+- **Dropped**: building a fresh `eps`/LightGBM forecaster in `sqa`. Superseded
+  by the existing Bayesian predictor.
+- **Proposed, not yet started**: extend `time_series_predictor` to multi-horizon
+  (k = 1…10), ideally sharing strength across horizons rather than fitting each
+  independently. Needs a read of `EXPLORATION.md` and
+  `03_stock_market_prediction_v2.rb` first.
+- **Proposed**: Laya sidecar as a drop-in alternative likelihood backend behind
+  the existing `llm_support.rb` provider dispatch, benchmarked against the
+  current LLM path on both latency and calibration (ECE).
+- **Open**: research JEV properly.
+- **Open**: indicator set for the feature vector; historical data source
+  (live Alpha Vantage vs cached) — both carried over from the previous entry.
+- **Open**: whether `bayesian_inference` graduates from `experiments/ai_misc/`
+  into the `sqa_project` workspace as a proper dependency, given
+  `sqa_polars_compat.rb` already reaches toward `SQA::DataFrame`.
+
+---
+
+## 2026-09-20 (port) — `bayesian_inference` graduates into the workspace as `sqa-bi`
+
+### Trigger
+
+The open item at the end of the previous entry — "whether
+`bayesian_inference` graduates from `experiments/ai_misc/` into the
+`sqa_project` workspace as a proper dependency" — answered yes. A bare
+`bundle gem sqa-bi` skeleton existed; this entry records filling it in.
+
+### What moved
+
+All of it, unchanged in substance:
+
+- `lib/bayesian_inference/*.rb` → `lib/sqa/bi/*.rb`, namespace
+  `BayesianInference` → `SQA::BI`, entry point `require "sqa/bi"`.
+- All 65 test methods, all 5 numbered examples, `EXPLORATION.md` (now
+  `docs/`), `llm_bayes_loop.svg`, `common.rb`, `pure_ruby_indicators.rb`.
+- Environment overrides renamed `SQA_BI_LLM_PROVIDER` / `SQA_BI_LLM_MODEL`,
+  with the old `BI_LLM_*` names kept as a fallback via a new
+  `LlmSupport.env_value`.
+
+### Finding 1 — the ruby_llm conflict was never a real blocker
+
+The prototype's `Gemfile` carried a comment asserting that `sqa` "cannot
+live in this bundle" because `sqa` → `ruby_llm-mcp` pins `ruby_llm ~> 1.9`
+against the `ruby_llm 2.0` the local provider gems need. Example 03 was
+therefore documented as "run directly, unbundled."
+
+The pin is real — `ruby_llm-mcp` 0.8.0 and 1.0.1 both require
+`ruby_llm ~> 1.9` — but the dependency is not on `sqa` directly. It comes
+in through `shared_tools`, and Bundler simply backs `shared_tools` down to
+0.2.3, which has no `ruby_llm-mcp` dependency at all. That is the same
+resolution `sqa`'s own `Gemfile.local.lock` already sits on.
+
+Verified: `sqa-bi/Gemfile.local` resolves `sqa 0.4.0` + `ruby_llm 2.0.0` +
+`shared_tools 0.2.3` + both provider gems, and `examples/03` runs end to
+end under `bundle exec` — 6761 days of T, 6739 feature vectors, full
+confusion matrix.
+
+### Finding 2 — two shim files had gone stale
+
+- `examples/sqa_polars_compat.rb` patched `sqa 0.0.38` against modern
+  `polars-df` (`read_csv dtypes:`, `Series#apply`, `with_column`, `sort
+  reverse:`) and forced Alpha Vantage compact fetches. Against `sqa 0.4.0`
+  none of it is needed — `grep` finds no remaining `.apply(`,
+  `with_column(`, `reverse:` or `dtypes:` in `sqa/lib`, and example 03
+  produces identical output with the require removed. **Deleted.**
+- `examples/pure_ruby_indicators.rb` claimed to exist because
+  "sqa-tai's ta_lib_ffi hangs against ta-lib 0.8.x". `sqa-tai` 0.4.0
+  replaced `ta_lib_ffi`; `SQA::TAI.sma` and `.rsi` both return correct
+  values immediately. **Kept, rationale rewritten** — it now exists so the
+  examples carry no `sqa-tai` dependency, with a pointer to `sqa-tai` for
+  production use.
+
+### Architectural decision — `sqa-bi` is a leaf, not an extension
+
+```
+sqa-tai  ─┐
+sqa-bi   ─┴→  sqa  →  sqa-cli / sqa-advisor / sqa-rails / sqa-sinatra
+```
+
+The gemspec declares **no runtime dependencies** and deliberately does not
+depend on `sqa`. The inference math is domain-agnostic, so `sqa` can
+depend on `sqa-bi` the way it depends on `sqa-tai`; a `sqa` dependency
+here would invert the graph and produce a cycle the moment `sqa` picks it
+up. `asgard` classifies it correctly on its own — `list_libs` returns
+`sqa`, `sqa-bi`, `sqa-tai`; it is absent from the extension set that
+`sync_rakefiles` and `sync_versions` target.
+
+`ruby_llm` stays a development dependency, required lazily inside
+`LlmSupport.build_chat`, so the KDE path loads without it.
+
+### Verification
+
+| Check | Result |
+|---|---|
+| Test parity with the prototype | 65 test methods in, 65 out |
+| `rake test` (prod bundle) | 65 tests, 130 assertions, 0 failures; 85.1% line coverage |
+| `rake test` (dev bundle, with `sqa`) | same |
+| `rake quality` | tests / flog / flay / reek all PASS |
+| `rubocop` | 19 files, no offenses |
+| Reek | 18 smells → 10 after fixing the trivial ones; 10 baselined |
+| Example 01, 02 | run clean |
+| Example 03 (needs `sqa`) | runs end to end under `bundle exec` |
+| Example 04 (LLM prior) | gemini-2.5-flash: data-only tie 0.358/0.358 → informed 0.531 for mild uptrend, confidence 19.9% → 37.2% — matches the prototype's documented result |
+| Example 05 (LLM likelihood) | network hypothesis reaches 99.7%, belief reverses on evidence 3–5 as documented |
+| Provider dispatch after the env rename | falls through lms → apfel → cloud correctly |
+
+Reek smells fixed rather than grandfathered: six `o` → `outcome` block
+params, `w` → `weight`, `u` → `normalized_distance`, `v1`/`v2` →
+`query`/`observed`, and a triple `features.size` call. The 10 left in
+`.quality/reek_baseline.txt` are deliberate: FeatureEnvy inside the
+`reduce`-based `entropy` / `kl_divergence_from_prior` /
+`euclidean_distance`, TooManyStatements in `configure_ruby_llm` and
+`compute_posterior`, and the BooleanParameter/ControlParameter pairs on
+`TimeSeriesPredictor#initialize(update_prior:)` and `#reset!(keep_prior:)`
+— API shape, not accidents.
+
+### Open / next
+
+Unchanged from the previous entry, minus the graduation question:
+
+- **Proposed, not started**: multi-horizon prediction (k = 1…10) in
+  `TimeSeriesPredictor`, sharing strength across horizons rather than
+  fitting each independently. Adjacent horizons are strongly correlated
+  and the outcome set is ordinal; neither should be discarded.
+- **Proposed**: Laya sidecar as a drop-in alternative likelihood backend
+  behind `LlmSupport`'s provider dispatch, benchmarked against the current
+  LLM path on latency and calibration (ECE).
+- **Kept as benchmark only**: `eps` / LightGBM, to score the posterior
+  against.
+- **Open**: research JEV properly.
+- **Open**: indicator set for the feature vector; historical data source.
+- **New, minor**: `sqa-bi` is at 0.1.0 while the workspace versions in
+  lockstep at 0.4.0 (`asgard set_version` / `bump` hit all components).
+  Decide whether to fold it into the lockstep or let it release
+  independently first.

data/docs/EXPLORATION.md

@@ -0,0 +1,128 @@
+# Bayesian Inference × LLMs — an Exploration
+
+This document maps the intersection between this library's Bayesian
+machinery and large language models, and records what has been built
+and verified so far.
+
+## The Core Insight
+
+LLMs and Bayes' theorem have exactly complementary failure modes:
+
+| | Semantic judgment | Probability arithmetic |
+|---|---|---|
+| **LLM** | excellent — can assess "how surprising is this log line if the DB were down?" | poor — anchors, double-counts evidence, drifts toward its first conclusion |
+| **This library** | none — KDE needs numeric feature vectors | exact — normalization, entropy, KL divergence, sequential updates |
+
+So the design rule for every experiment here:
+
+> **The LLM judges. Ruby computes.**
+> Ask the LLM only for isolated, independent judgments (a weight, a
+> conditional probability). Never ask it to accumulate, normalize, or
+> update beliefs — that is Bayes' job, done in Ruby.
+
+![LLM–Bayes loop](assets/diagrams/llm-bayes-loop.svg)
+
+## Pattern 1: LLM as Prior Elicitor (built ✅)
+
+The eternal objection to Bayesian methods is "where does the prior come
+from?" An LLM is a queryable compression of domain knowledge — exactly
+the thing a prior is supposed to encode.
+
+`LlmPriorElicitor` takes a natural-language situation description and
+the outcome set, asks the LLM for relative weights, then floors,
+normalizes, and validates them through the existing `Prior` class.
+
+```ruby
+elicitor = SQA::BI::LlmPriorElicitor.new(
+  outcomes: [-2, -1, 0, 1, 2],
+  outcome_descriptions: { -2 => 'strong downtrend', ..., 2 => 'strong uptrend' }
+)
+prior = elicitor.elicit("The Fed unexpectedly cut rates by 50bp...")
+```
+
+**Verified result** (`examples/04_llm_elicited_prior.rb`, gemini-2.5-flash):
+with only 5 training observations, the data-only posterior was a dead
+tie between "sideways" and "mild uptrend" (0.358 each). The LLM read
+the bullish market context, produced a prior peaked at +1/+2, and the
+informed posterior broke the tie: mild uptrend at 50.0%, confidence up
+from 19.9% to 30.1%. As real data accumulates, the KDE likelihood
+dominates and the influence of the elicited prior correctly fades.
+
+**When it matters:** cold starts, regime changes, and any small-data
+setting — precisely where KDE is weakest.
+
+## Pattern 2: LLM as Likelihood Function (built ✅)
+
+`Likelihood` (KDE) requires numeric features and history. But much
+evidence is text: log lines, incident reports, witness statements.
+`LlmLikelihoodEstimator` asks the LLM one narrow question per
+(evidence, hypothesis) pair — *"assuming H is true, how probable is
+this evidence?"* — and Ruby chains the updates:
+
+```
+posterior_n ∝ P(evidence_n | H) × posterior_{n-1}
+```
+
+Likelihoods are clamped to [0.001, 0.999] so an overconfident LLM can
+never zero out a hypothesis in one step (Cromwell's rule), which is
+what keeps later contradicting evidence able to reverse the belief.
+
+**Verified result** (`examples/05_llm_likelihood_diagnosis.rb`): a
+production-outage diagnosis over three hypotheses. After evidence 1–2,
+`bad_deploy` led at 78.8%. Evidence 3 ("rollback didn't help") and 4
+("cross-AZ ping 1ms → 900ms") cleanly reversed the belief; final
+posterior: `network` at 99.96%. Information gain per update ranged
+0.025–0.959 bits — the engine also tells you *which evidence mattered*.
+
+A single LLM asked to track the same five facts in prose typically
+anchors on the deploy story. Externalizing the belief state into a
+posterior removes that failure mode entirely.
+
+## Patterns Not Yet Built (future experiments)
+
+1. **Bayesian calibration of LLM outputs** — treat the LLM as a noisy
+   sensor with a measured confusion matrix P(LLM says j | truth is i),
+   estimated from a labeled set. Then an LLM classification becomes a
+   likelihood column and Bayes yields *calibrated* posteriors instead
+   of the LLM's overconfident self-reported probabilities.
+2. **Self-consistency as sampling** — query the LLM k times at
+   temperature > 0 and treat the answers as draws; update a Dirichlet
+   posterior over the answer distribution. Gives error bars on LLM
+   judgments and a principled stopping rule ("stop sampling when the
+   95% credible interval no longer overlaps").
+3. **Bandwidth/hyperparameter elicitation** — let an LLM read a
+   dataset description and suggest KDE bandwidth and outcome coding,
+   closing the last manual knob in `TimeSeriesPredictor`.
+4. **Posterior narration** — the inverse direction: hand the LLM a
+   posterior + KL trail and have it write the incident-report
+   paragraph. Zero math risk, pure language work.
+
+## Engineering Notes
+
+- **New files:** `lib/sqa/bi/llm_support.rb` (JSON
+  extraction, re-keying, normalization, clamping — all module
+  functions, testable in isolation), `llm_prior_elicitor.rb`,
+  `llm_likelihood_estimator.rb`.
+- **Dependency discipline:** `ruby_llm` is required lazily inside
+  `LlmSupport.build_chat`, so the core math library still loads without
+  it. Both classes accept an injectable `chat:` object; the test suite
+  (`FakeChat` in `test/test_helper.rb`) runs with zero network calls.
+- **Provider selection — local first:** `LlmSupport.resolve_provider`
+  auto-detects, in order: LM Studio via `ruby_llm-providers-lms`
+  (`http://localhost:1234/v1`), Apfel / Apple Foundation Models via
+  `ruby_llm-providers-apfel` (`http://127.0.0.1:11434/v1`), then cloud.
+  `SQA_BI_LLM_PROVIDER` (`lms` | `apfel` | `cloud`) and `SQA_BI_LLM_MODEL`
+  override detection. For local servers, `choose_local_model` prefers
+  qwen models (they honor JSON prompts most reliably in LM Studio),
+  then gpt-oss, skipping embedding/OCR models. Both local paths are
+  verified: qwen3.8-27b via LM Studio gave a bullish prior peaked at
+  +1; Apple's 3B on-device model gave a more cautious prior peaked
+  at 0 — model quality shows up directly as prior sharpness. Note: as
+  of 2026-09-18 the `ANTHROPIC_API_KEY` in this machine's environment
+  returns 401; the OpenAI key has no credits; the Gemini key works.
+- **Ruby 4 note:** `logger` is no longer a default gem; it is in the
+  Gemfile because `ruby_llm` 1.16 requires it.
+- **Test suite:** 65 runs, 0 failures, 85% line coverage.
+  `test_helper.rb` does `Object.include(DebugMe)` — the lib classes call
+  `debug_me` and previously only the examples included it, so the suite
+  could not run under `rake test`.

data/docs/api/index.md

@@ -0,0 +1,66 @@
+# API Reference
+
+Every public method, with its contract. For narrative explanation see the
+[Guide](../guide/prior.md).
+
+## Namespace
+
+```ruby
+require "sqa/bi"   # NOT "sqa-bi"
+```
+
+Everything lives under `SQA::BI`. The module can be included for brevity:
+
+```ruby
+include SQA::BI
+
+predictor = TimeSeriesPredictor.new(outcomes: [-1, 0, 1])
+```
+
+## Module methods
+
+### `SQA::BI.predictor(outcomes:, bandwidth: 1.0, **options)`
+
+Convenience constructor. Forwards everything to
+[`TimeSeriesPredictor.new`](time-series-predictor.md).
+
+```ruby
+SQA::BI.predictor(outcomes: [-2, -1, 0, 1, 2], bandwidth: 0.5)
+```
+
+### `SQA::BI::VERSION`
+
+The gem version string.
+
+### `SQA::BI::Error`
+
+`StandardError` subclass. Raised for malformed LLM responses, an unavailable
+local chat model, and a failed `ruby_llm` load.
+
+## Classes
+
+| Class | Responsibility |
+|---|---|
+| [`Prior`](prior.md) | `P(outcome)` — belief before evidence |
+| [`Likelihood`](likelihood.md) | `P(features \| outcome)` — Gaussian KDE |
+| [`Posterior`](posterior.md) | `P(outcome \| features)` — Bayes plus uncertainty measures |
+| [`TimeSeriesPredictor`](time-series-predictor.md) | the `train` / `predict` facade |
+| [`LlmPriorElicitor`](llm-elicitors.md#sqabillmpriorelicitor) | a prior from prose |
+| [`LlmLikelihoodEstimator`](llm-elicitors.md#sqabillmlikelihoodestimator) | likelihoods from text evidence |
+| [`LlmSupport`](llm-support.md) | provider resolution and LLM-response plumbing |
+
+## Conventions
+
+**Immutability.** `Prior` and `Posterior` never mutate. `Prior#update_from_observations`
+and `#combine` return new instances.
+
+**Keyword arguments** for anything optional or non-obvious — `outcome:`,
+`bandwidth:`, `smoothing:`, `weight:`, `rng:`.
+
+**`ArgumentError` for contract violations** — bad dimensions, unknown outcomes,
+probabilities that don't sum to 1. `SQA::BI::Error` for LLM and provider
+failures.
+
+**Hash keys are your outcome objects**, not strings. Integers, symbols, and
+strings all work; `rekey_to_outcomes` maps JSON's string keys back onto
+whatever you used.

data/docs/api/likelihood.md

@@ -0,0 +1,78 @@
+# SQA::BI::Likelihood
+
+`P(features | outcome)` by Gaussian kernel density estimation over stored
+observations.
+
+Unlike `Prior` and `Posterior`, this class **is** mutable — `add_observation`
+appends in place.
+
+## Constructor
+
+### `.new(observations = [], bandwidth: 1.0)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `observations` | `Array<Hash>` | each `{ features: [...], outcome: ... }` |
+| `bandwidth:` | `Float` | kernel width `h`; default `1.0` |
+
+```ruby
+SQA::BI::Likelihood.new(
+  [{ features: [1.0, 2.0], outcome: 1 }],
+  bandwidth: 0.5
+)
+```
+
+## Attributes
+
+| Reader | Type | Description |
+|---|---|---|
+| `observations` | `Array<Hash>` | the stored observations |
+| `bandwidth` | `Float` | current kernel width |
+
+## Instance methods
+
+### `#add_observation(features, outcome)` → `void`
+
+Appends an observation and regroups by outcome.
+
+```ruby
+likelihood.add_observation([1.1, 2.1], 1)
+```
+
+### `#compute(features, outcomes)` → `Hash`
+
+Likelihood for every outcome, normalized to sum to 1.
+
+```ruby
+likelihood.compute([1.0, 2.0], [-1, 0, 1])
+# => {-1 => 0.05, 0 => 0.15, 1 => 0.80}
+```
+
+With no observations at all, returns a uniform distribution — the posterior then
+equals the prior, which is correct.
+
+### `#estimate_density(features, outcome)` → `Float`
+
+Unnormalized kernel density for a single outcome.
+
+$$\frac{1}{n}\sum_{i=1}^{n} K\!\left(\frac{\lVert x - x_i\rVert}{h}\right), \quad K(u) = \frac{1}{\sqrt{2\pi}}e^{-u^2/2}$$
+
+Returns `1e-10` — never `0.0` — for an outcome with no observations.
+
+**Raises `ArgumentError`** when a stored vector's dimension differs from the
+query's.
+
+### `#size` → `Integer`
+
+Number of stored observations.
+
+### `#empty?` → `Boolean`
+
+### `#outcome_counts` → `Hash`
+
+`{outcome => Integer}`. Feeds
+[the predictor's prior update](../guide/prior.md#automatic-updating-inside-the-predictor).
+
+```ruby
+likelihood.outcome_counts   # => {1 => 3, -2 => 1}
+```