sqa-bi 0.1.0

data/docs/api/llm-elicitors.md

@@ -0,0 +1,119 @@
+# LLM Elicitors
+
+The two classes that turn language into numbers. Both accept an injectable
+`chat:`, and both expose their prompt building and response parsing as public,
+pure methods so they can be tested with no network.
+
+---
+
+## SQA::BI::LlmPriorElicitor
+
+A [`Prior`](prior.md) from a natural-language description of a situation.
+Narrative: [Prior Elicitation](../llm/prior-elicitation.md).
+
+### `.new(outcomes:, outcome_descriptions: {}, chat: nil, model: nil, provider: nil)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `outcomes:` | `Array` | the outcome set the prior ranges over |
+| `outcome_descriptions:` | `Hash` | `{outcome => "human label"}` used in the prompt |
+| `chat:` | `#ask, nil` | injectable chat; defaults to a lazily built `RubyLLM::Chat` |
+| `model:` | `String, nil` | model id; `nil` resolves per provider |
+| `provider:` | `Symbol, nil` | `:lms`, `:apfel`, `:cloud`; `nil` auto-detects |
+
+### `#elicit(context)` → `Prior`
+
+Asks the LLM for relative weights over the outcomes, given a prose description,
+then floors, normalizes and validates them.
+
+```ruby
+prior = elicitor.elicit("The Fed unexpectedly cut rates by 50bp...")
+```
+
+### `#prior_from_response(content)` → `Prior`
+
+Pure. `extract_json` → `rekey_to_outcomes` → `normalize_distribution` → `Prior`.
+
+```ruby
+elicitor.prior_from_response('{"-1": 10, "0": 20, "1": 70}')
+```
+
+### `#build_prompt(context)` → `String`
+
+Pure. Public so the wording can be tested and iterated on.
+
+### Attributes
+
+`outcomes`, `outcome_descriptions`, `model`, `provider`
+
+---
+
+## SQA::BI::LlmLikelihoodEstimator
+
+`P(evidence | hypothesis)` for textual evidence. Narrative:
+[Likelihood Estimation](../llm/likelihood-estimation.md).
+
+### `.new(hypotheses:, chat: nil, model: nil, provider: nil)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `hypotheses:` | `Hash` | `{id => description}`; ids become the outcome keys |
+| `chat:` | `#ask, nil` | injectable chat |
+| `model:` | `String, nil` | model id |
+| `provider:` | `Symbol, nil` | `:lms`, `:apfel`, `:cloud` |
+
+### `#likelihoods(evidence)` → `Hash`
+
+`{hypothesis_id => Float}`, each clamped to `(0, 1)`.
+
+```ruby
+estimator.likelihoods("Error rate spiked 2 minutes after deploy")
+# => { bad_deploy: 0.9, database: 0.2, network: 0.15 }
+```
+
+!!! important "These need not sum to 1"
+    Each is an independent judgment: *if this hypothesis were true, how
+    surprising would this evidence be?*
+
+### `#likelihoods_from_response(content)` → `Hash`
+
+Pure. `extract_json` → `rekey_to_outcomes` → `clamp_likelihood` on every value.
+
+```ruby
+estimator.likelihoods_from_response('{"a": 1.0, "b": 0.0}')
+# => { a: 0.999, b: 0.001 }
+```
+
+### `#build_prompt(evidence)` → `String`
+
+Pure.
+
+### Attributes
+
+`hypotheses`, `model`, `provider`
+
+---
+
+## Testing both without a network
+
+```ruby
+class FakeChat
+  Response = Struct.new(:content)
+  attr_reader :last_prompt
+
+  def initialize(content) = @content = content
+
+  def ask(prompt)
+    @last_prompt = prompt
+    Response.new(@content)
+  end
+end
+
+chat = FakeChat.new('{"-1": 10, "0": 20, "1": 70}')
+elicitor = SQA::BI::LlmPriorElicitor.new(outcomes: [-1, 0, 1], chat: chat)
+
+elicitor.elicit("bullish setup").probability(1)   # => 0.7
+chat.last_prompt                                   # assert on prompt wording
+```
+
+This is what the gem's own suite does — no test may reach a real provider.

data/docs/api/llm-support.md

@@ -0,0 +1,136 @@
+# SQA::BI::LlmSupport
+
+Shared plumbing for the classes that get numbers out of an LLM. Every method is
+a `module_function`, so each is callable and testable in isolation.
+
+```ruby
+S = SQA::BI::LlmSupport
+```
+
+## Constants
+
+| Constant | Value |
+|---|---|
+| `LMS_DEFAULT_BASE` | `http://localhost:1234/v1` |
+| `APFEL_DEFAULT_BASE` | `http://127.0.0.1:11434/v1` |
+| `CLOUD_DEFAULT_MODEL` | `claude-haiku-4-5` |
+
+## Provider resolution
+
+### `.resolve_provider` → `Symbol`
+
+`:lms`, `:apfel`, or `:cloud`. Checks the environment override first, then
+probes each local server in order. See [Providers](../llm/providers.md).
+
+### `.server_alive?(base, timeout: 1)` → `Boolean`
+
+`GET {base}/models`, true on a 2xx. Any exception is false.
+
+### `.list_local_models(base)` → `Array<String>`
+
+Model ids the server is serving right now. `[]` on any failure.
+
+### `.choose_local_model(ids)` → `String, nil`
+
+Rejects anything matching `/embed|ocr/i`, then prefers qwen, then gpt-oss, then
+the first remaining id. `nil` when nothing is eligible.
+
+### `.local_api_base(provider)` → `String, nil`
+
+API base for `:lms` or `:apfel`; `nil` for `:cloud` or anything else.
+
+### `.lms_api_base` / `.apfel_api_base` → `String`
+
+Honor `LMS_API_BASE` / `APFEL_API_BASE`.
+
+### `.env_value(*names)` → `String, nil`
+
+First non-blank value among the named environment variables.
+
+### `.env_model` → `String, nil`
+
+`env_value('SQA_BI_LLM_MODEL', 'BI_LLM_MODEL')`.
+
+## Visibility
+
+### `.resolution_label(provider, model, base)` → `String`
+
+Pure formatter. No I/O.
+
+```ruby
+S.resolution_label(:lms, "qwen/qwen3.8-27b", "http://localhost:1234/v1")
+# => "lms — qwen/qwen3.8-27b at http://localhost:1234/v1"
+
+S.resolution_label(:cloud, "claude-haiku-4-5", nil)
+# => "cloud — claude-haiku-4-5"
+
+S.resolution_label(:lms, nil, "http://localhost:1234/v1")
+# => "lms — (no chat model available) at http://localhost:1234/v1"
+```
+
+### `.current_resolution(model = nil, provider: nil)` → `String`
+
+Where the next chat would actually go. Probes the local servers, so it costs one
+HTTP round trip. Pass `provider: :cloud` to skip the probe.
+
+```ruby
+S.current_resolution
+# => "lms — qwen/qwen3.8-27b at http://localhost:1234/v1"
+```
+
+Use it to surface the [silent cloud fallback](../llm/providers.md#making-resolution-visible).
+
+## Chat construction
+
+### `.build_chat(model = nil, provider: nil)` → `RubyLLM::Chat`
+
+Requires `ruby_llm` lazily, configures it, resolves the provider, and returns a
+chat. **Raises `SQA::BI::Error`** if `ruby_llm` cannot be loaded, or if a local
+provider has no eligible chat model.
+
+### `.local_chat(provider, model, base)` → `RubyLLM::Chat`
+
+### `.require_ruby_llm` → `void`
+
+Requires `ruby_llm`, converting both `LoadError` and `Gem::ConflictError` (which
+is itself a `LoadError`) into one actionable `SQA::BI::Error`.
+
+### `.configure_ruby_llm` → `void`
+
+Registers the local provider gems and wires whichever cloud API keys are
+present. Runs once; safe to call repeatedly.
+
+### `.require_local_providers` → `void`
+
+Requires both provider gems, swallowing `LoadError`. A missing gem disables only
+that provider.
+
+## Response plumbing
+
+### `.extract_json(content)` → `Hash`
+
+Pulls a Hash out of an already-parsed Hash, a raw JSON string, or prose
+containing a JSON object (including inside a ```json fence).
+
+**Raises `SQA::BI::Error`** when no JSON object is found or it is malformed.
+
+### `.rekey_to_outcomes(raw, outcomes)` → `Hash`
+
+JSON keys are always strings; outcomes may be integers or symbols. Matches on
+`to_s`. Missing outcomes get `0.0`.
+
+```ruby
+S.rekey_to_outcomes({ "1" => 70, "0" => 20 }, [-1, 0, 1])
+# => {-1 => 0.0, 0 => 20.0, 1 => 70.0}
+```
+
+### `.normalize_distribution(weights, epsilon: 1e-6)` → `Hash`
+
+Floors at zero, adds `epsilon`, normalizes to sum to 1. The epsilon is
+[Cromwell's rule](../guide/prior.md#laplace-smoothing) — no outcome is ever
+exactly zero.
+
+### `.clamp_likelihood(value, floor: 0.001, ceiling: 0.999)` → `Float`
+
+Keeps an overconfident `0.0` or `1.0` from zeroing out or saturating the
+posterior in one update.

data/docs/api/posterior.md

@@ -0,0 +1,106 @@
+# SQA::BI::Posterior
+
+`P(outcome | features)` — the result of Bayes' theorem, plus the measures that
+say how much to trust it.
+
+Immutable; everything is computed at construction.
+
+## Constructor
+
+### `.new(prior, likelihoods)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `prior` | `Prior` | the prior distribution |
+| `likelihoods` | `Hash` | `{outcome => P(data \| outcome)}` |
+
+```ruby
+SQA::BI::Posterior.new(prior, { -1 => 0.1, 0 => 0.3, 1 => 0.6 })
+```
+
+Computes `likelihood × prior`, normalized. If the unnormalized total is `0.0`
+it falls back to the prior rather than dividing by zero.
+
+## Attributes
+
+| Reader | Type | Description |
+|---|---|---|
+| `prior` | `Prior` | the prior it was built from |
+| `likelihoods` | `Hash` | the likelihoods it was built from |
+| `probabilities` | `Hash` | the normalized posterior |
+
+## Reading the distribution
+
+### `#probability(outcome)` → `Float`
+
+**Alias:** `#[]`
+
+### `#max_outcome` → outcome
+
+The MAP estimate — highest posterior probability.
+
+!!! tip "Read `confidence` alongside it"
+    `1` at 74% and `1` at 26% are different situations that `max_outcome`
+    reports identically.
+
+### `#top_outcomes(n = 3)` → `Array<Array>`
+
+`[[outcome, probability], ...]` sorted by probability **descending**.
+
+```ruby
+posterior.top_outcomes(3)   # => [[1, 0.74], [0, 0.15], [-1, 0.06]]
+```
+
+### `#to_a` → `Array<Array>`
+
+`[[outcome, probability], ...]` sorted by **outcome** ascending — preserves the
+ordinal scale, which is what you want for charting.
+
+### `#to_h` → `Hash`
+
+A copy of the probabilities.
+
+## Uncertainty
+
+### `#entropy` → `Float`
+
+Shannon entropy in bits. `0.0` = certain; `log₂(n)` = uniform.
+
+### `#confidence` → `Float`
+
+`1 - entropy / log₂(n)`. Always in `[0, 1]`, so it is comparable across
+different outcome-set sizes and is the right thing to threshold on.
+
+### `#kl_divergence_from_prior` → `Float`
+
+$$D_{KL} = \sum_i p_i \log_2 \frac{p_i}{q_i}$$
+
+Bits of information this evidence added. Always ≥ 0; zero means the evidence
+moved your belief not at all. See [Quantifying Uncertainty](../guide/uncertainty.md).
+
+## Sampling
+
+### `#sample(rng: Random.new)` → outcome
+
+One draw by inverse-CDF sampling.
+
+### `#samples(n, rng: Random.new)` → `Array`
+
+```ruby
+posterior.samples(10_000, rng: Random.new(42))
+```
+
+Pass `rng:` for reproducibility.
+
+## Reporting
+
+### `#to_s` → `String`
+
+```
+Posterior(-2: 0.010, -1: 0.060, 0: 0.150, 1: 0.740, 2: 0.040)
+```
+
+### `#summary` → `String`
+
+Multi-line report: MAP outcome, confidence, entropy, KL divergence, and the full
+distribution as both decimals and percentages.

data/docs/api/prior.md

@@ -0,0 +1,81 @@
+# SQA::BI::Prior
+
+Prior probability distribution over discrete outcomes.
+
+Immutable — every method that changes something returns a new instance.
+
+## Constructor
+
+### `.new(outcomes, probabilities = nil)`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `outcomes` | `Array` | discrete outcomes; sorted on construction |
+| `probabilities` | `Hash, nil` | `{outcome => Float}`; `nil` gives a uniform prior |
+
+```ruby
+SQA::BI::Prior.new([-2, -1, 0, 1, 2])
+SQA::BI::Prior.new([-1, 0, 1], { -1 => 0.2, 0 => 0.5, 1 => 0.3 })
+```
+
+**Raises `ArgumentError`** when probabilities are supplied and: an outcome is
+missing, the values don't sum to 1.0 (tolerance 1e-6), or any value is negative.
+
+## Attributes
+
+| Reader | Type | Description |
+|---|---|---|
+| `outcomes` | `Array` | the sorted outcome set |
+| `probabilities` | `Hash` | `{outcome => Float}` |
+
+## Instance methods
+
+### `#probability(outcome)` → `Float`
+
+Probability of one outcome; `0.0` for an unknown one.
+
+**Alias:** `#[]`
+
+```ruby
+prior.probability(0)   # => 0.2
+prior[0]               # => 0.2
+```
+
+### `#update_from_observations(observations, smoothing: 1.0)` → `Prior`
+
+New prior from observed frequencies, with Laplace smoothing:
+
+$$P(\text{outcome}) = \frac{\text{count} + \alpha}{\text{total} + \alpha n}$$
+
+| Parameter | Type | Description |
+|---|---|---|
+| `observations` | `Hash` | `{outcome => Integer count}` |
+| `smoothing:` | `Float` | α; default `1.0`. Higher pulls toward uniform |
+
+```ruby
+prior.update_from_observations({ -1 => 5, 0 => 20, 1 => 12 })
+prior.update_from_observations(counts, smoothing: 5.0)
+```
+
+Smoothing guarantees no outcome gets probability zero — see
+[Cromwell's rule](../guide/prior.md#laplace-smoothing).
+
+### `#combine(other_prior, weight: 0.5)` → `Prior`
+
+Weighted average. `weight` applies to the receiver, `1 - weight` to the argument.
+
+```ruby
+data_prior.combine(elicited_prior, weight: 0.7)
+```
+
+**Raises `ArgumentError`** if the two priors span different outcomes.
+
+### `#entropy` → `Float`
+
+Shannon entropy in bits. `0.0` when certain; `log₂(n)` when uniform.
+
+### `#to_s` → `String`
+
+```
+Prior(-2: 0.100, -1: 0.150, 0: 0.500, 1: 0.150, 2: 0.100)
+```

data/docs/api/time-series-predictor.md

@@ -0,0 +1,96 @@
+# SQA::BI::TimeSeriesPredictor
+
+The facade over [`Prior`](prior.md), [`Likelihood`](likelihood.md) and
+[`Posterior`](posterior.md).
+
+## Constructor
+
+### `.new(outcomes:, bandwidth: 1.0, prior_probabilities: nil, update_prior: true)`
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `outcomes:` | `Array` | required | discrete outcome set; sorted |
+| `bandwidth:` | `Float` | `1.0` | KDE kernel width |
+| `prior_probabilities:` | `Hash, nil` | `nil` | explicit prior; `nil` is uniform |
+| `update_prior:` | `Boolean` | `true` | relearn the prior from frequencies while training |
+
+```ruby
+SQA::BI::TimeSeriesPredictor.new(
+  outcomes: [-2, -1, 0, 1, 2],
+  bandwidth: 0.5,
+  prior_probabilities: elicited.probabilities,
+  update_prior: false
+)
+```
+
+`SQA::BI.predictor(...)` is a shorthand for the same thing.
+
+## Attributes
+
+| Reader | Type | Description |
+|---|---|---|
+| `outcomes` | `Array` | the sorted outcome set |
+| `prior` | `Prior` | current prior |
+| `likelihood` | `Likelihood` | the KDE estimator |
+| `feature_dimension` | `Integer, nil` | fixed by the first `train`; `nil` before |
+| `bandwidth` | `Float` | current kernel width |
+
+## Training
+
+### `#train(features, outcome:)` → `self`
+
+```ruby
+predictor.train([1.0, 2.0, 3.0], outcome: 1)
+```
+
+**Raises `ArgumentError`** when features are not an array of numbers, the
+dimension differs from the established one, or the outcome is not in the set.
+
+With `update_prior: true`, the prior is relearned once
+`likelihood.size >= outcomes.size` — the guard stops the first few observations
+stamping a lopsided prior onto the model.
+
+### `#train_batch(observations)` → `self`
+
+```ruby
+predictor.train_batch([{ features: [...], outcome: 1 }, ...])
+```
+
+## Prediction
+
+### `#predict(features)` → `Posterior`
+
+The full distribution. Prefer this.
+
+### `#predict_outcome(features)` → outcome
+
+`predict(features).max_outcome` — discards the uncertainty.
+
+### `#predict_proba(features)` → `Hash`
+
+`predict(features).to_h`.
+
+## State
+
+| Method | Returns | Description |
+|---|---|---|
+| `#trained?` | `Boolean` | any observations yet? |
+| `#training_size` | `Integer` | observation count |
+| `#training_distribution` | `Hash` | `{outcome => count}` — check this for class imbalance |
+| `#summary` | `String` | outcomes, dimension, sample count, bandwidth, prior, distribution |
+
+## Mutation
+
+### `#reset!(keep_prior: false)` → `self`
+
+Clears observations and the feature dimension. Also resets the prior to uniform
+unless `keep_prior: true`.
+
+### `#bandwidth=(new_bandwidth)` → `self`
+
+Rebuilds the KDE from the existing observations — nothing is lost, which makes a
+[bandwidth sweep](../guide/tuning.md#sweeping-it) cheap.
+
+```ruby
+predictor.bandwidth = 0.5
+```

data/docs/assets/css/custom.css

@@ -0,0 +1,25 @@
+/* Custom styles for SQA::BI documentation */
+
+/* Diagrams are authored for a dark theme on a transparent background.
+   In light mode they need a dark plate behind them to stay legible. */
+[data-md-color-scheme="default"] img[src*="/diagrams/"] {
+  background-color: #282a36;
+  border-radius: 8px;
+  padding: 0.75rem;
+}
+
+img[src*="/diagrams/"] {
+  width: 100%;
+  height: auto;
+}
+
+/* Outcome scale used throughout the guide: negative red, zero amber,
+   positive green — matching the terminal output of the demos. */
+.outcome-down { color: #ff5555; font-weight: 600; }
+.outcome-flat { color: #ffb86c; font-weight: 600; }
+.outcome-up   { color: #50fa7b; font-weight: 600; }
+
+/* Keep wide probability tables from wrapping mid-number. */
+table td code {
+  white-space: nowrap;
+}

data/docs/assets/diagrams/architecture.svg

@@ -0,0 +1,75 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 520" font-family="Helvetica, Arial, sans-serif">
+  <!-- Dark theme, transparent background -->
+  <defs>
+    <marker id="archArrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#8be9fd"/>
+    </marker>
+    <marker id="archArrowAmber" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#ffb86c"/>
+    </marker>
+  </defs>
+
+  <text x="480" y="32" text-anchor="middle" fill="#f8f8f2" font-size="22" font-weight="bold">SQA::BI architecture</text>
+  <text x="480" y="54" text-anchor="middle" fill="#9aa0b0" font-size="13">a pure-Ruby core, with an optional LLM wing that only ever supplies numbers</text>
+
+  <!-- Core math region -->
+  <rect x="30" y="82" width="520" height="300" rx="14" fill="none" stroke="#6272a4" stroke-width="1.5" stroke-dasharray="6 4"/>
+  <text x="48" y="104" fill="#6272a4" font-size="12" font-weight="bold">CORE — no dependencies, always available</text>
+
+  <!-- TimeSeriesPredictor -->
+  <rect x="60" y="120" width="200" height="78" rx="10" fill="none" stroke="#8be9fd" stroke-width="2.5"/>
+  <text x="160" y="148" text-anchor="middle" fill="#8be9fd" font-size="14" font-weight="bold">TimeSeriesPredictor</text>
+  <text x="160" y="169" text-anchor="middle" fill="#d6d9e0" font-size="11">train / predict facade</text>
+  <text x="160" y="186" text-anchor="middle" fill="#9aa0b0" font-size="11">owns outcomes + bandwidth</text>
+
+  <!-- Prior -->
+  <rect x="60" y="240" width="145" height="76" rx="10" fill="none" stroke="#bd93f9" stroke-width="2"/>
+  <text x="132" y="266" text-anchor="middle" fill="#bd93f9" font-size="13" font-weight="bold">Prior</text>
+  <text x="132" y="286" text-anchor="middle" fill="#d6d9e0" font-size="11">P(outcome)</text>
+  <text x="132" y="303" text-anchor="middle" fill="#9aa0b0" font-size="10">Laplace smoothing</text>
+
+  <!-- Likelihood -->
+  <rect x="225" y="240" width="145" height="76" rx="10" fill="none" stroke="#ffb86c" stroke-width="2"/>
+  <text x="297" y="266" text-anchor="middle" fill="#ffb86c" font-size="13" font-weight="bold">Likelihood</text>
+  <text x="297" y="286" text-anchor="middle" fill="#d6d9e0" font-size="11">P(features | outcome)</text>
+  <text x="297" y="303" text-anchor="middle" fill="#9aa0b0" font-size="10">Gaussian KDE</text>
+
+  <!-- Posterior -->
+  <rect x="390" y="240" width="145" height="76" rx="10" fill="none" stroke="#50fa7b" stroke-width="2"/>
+  <text x="462" y="266" text-anchor="middle" fill="#50fa7b" font-size="13" font-weight="bold">Posterior</text>
+  <text x="462" y="286" text-anchor="middle" fill="#d6d9e0" font-size="11">P(outcome | features)</text>
+  <text x="462" y="303" text-anchor="middle" fill="#9aa0b0" font-size="10">entropy · KL · sampling</text>
+
+  <!-- Edges from predictor -->
+  <path d="M 130 198 L 130 240" fill="none" stroke="#8be9fd" stroke-width="1.6" marker-end="url(#archArrow)"/>
+  <path d="M 190 198 L 280 240" fill="none" stroke="#8be9fd" stroke-width="1.6" marker-end="url(#archArrow)"/>
+  <path d="M 240 198 L 440 240" fill="none" stroke="#8be9fd" stroke-width="1.6" marker-end="url(#archArrow)"/>
+
+  <text x="480" y="352" text-anchor="middle" fill="#9aa0b0" font-size="11" font-style="italic">Bayes' theorem is computed here, in Ruby, exactly — never delegated</text>
+
+  <!-- LLM wing -->
+  <rect x="580" y="82" width="350" height="300" rx="14" fill="none" stroke="#6272a4" stroke-width="1.5" stroke-dasharray="6 4"/>
+  <text x="598" y="104" fill="#6272a4" font-size="12" font-weight="bold">OPTIONAL — ruby_llm required lazily</text>
+
+  <rect x="610" y="120" width="290" height="66" rx="10" fill="none" stroke="#ff79c6" stroke-width="2"/>
+  <text x="755" y="145" text-anchor="middle" fill="#ff79c6" font-size="13" font-weight="bold">LlmPriorElicitor</text>
+  <text x="755" y="166" text-anchor="middle" fill="#9aa0b0" font-size="11">context in prose → relative weights → Prior</text>
+
+  <rect x="610" y="202" width="290" height="66" rx="10" fill="none" stroke="#ff79c6" stroke-width="2"/>
+  <text x="755" y="227" text-anchor="middle" fill="#ff79c6" font-size="13" font-weight="bold">LlmLikelihoodEstimator</text>
+  <text x="755" y="248" text-anchor="middle" fill="#9aa0b0" font-size="11">text evidence → P(e | H) per hypothesis</text>
+
+  <rect x="610" y="284" width="290" height="76" rx="10" fill="none" stroke="#f1fa8c" stroke-width="2"/>
+  <text x="755" y="309" text-anchor="middle" fill="#f1fa8c" font-size="13" font-weight="bold">LlmSupport</text>
+  <text x="755" y="329" text-anchor="middle" fill="#d6d9e0" font-size="11">provider resolution · JSON extraction</text>
+  <text x="755" y="346" text-anchor="middle" fill="#d6d9e0" font-size="11">re-keying · normalizing · clamping</text>
+
+  <!-- LLM wing feeds the core -->
+  <path d="M 610 153 L 205 258" fill="none" stroke="#ffb86c" stroke-width="1.6" stroke-dasharray="5 4" marker-end="url(#archArrowAmber)"/>
+  <path d="M 610 235 L 370 268" fill="none" stroke="#ffb86c" stroke-width="1.6" stroke-dasharray="5 4" marker-end="url(#archArrowAmber)"/>
+
+  <!-- Footer contract -->
+  <rect x="140" y="412" width="680" height="72" rx="12" fill="none" stroke="#50fa7b" stroke-width="2"/>
+  <text x="480" y="440" text-anchor="middle" fill="#50fa7b" font-size="15" font-weight="bold">The LLM judges. Ruby computes.</text>
+  <text x="480" y="463" text-anchor="middle" fill="#9aa0b0" font-size="11">the LLM answers one isolated question at a time and never accumulates, normalizes or updates a belief</text>
+</svg>