sqa-bi 0.1.0

data/docs/assets/diagrams/bayes-pipeline.svg

@@ -0,0 +1,48 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 940 420" font-family="Helvetica, Arial, sans-serif">
+  <!-- Dark theme, transparent background -->
+  <defs>
+    <marker id="arrowCyan" 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>
+  </defs>
+
+  <text x="470" y="34" text-anchor="middle" fill="#f8f8f2" font-size="22" font-weight="bold">Prior × Likelihood → Posterior</text>
+  <text x="470" y="56" text-anchor="middle" fill="#9aa0b0" font-size="13">one prediction, from belief and evidence to a distribution over outcomes</text>
+
+  <!-- Prior: purple = belief before data -->
+  <rect x="40" y="110" width="230" height="150" rx="12" fill="none" stroke="#bd93f9" stroke-width="2.5"/>
+  <text x="155" y="140" text-anchor="middle" fill="#bd93f9" font-size="16" font-weight="bold">Prior</text>
+  <text x="155" y="162" text-anchor="middle" fill="#9aa0b0" font-size="12" font-style="italic">P(outcome)</text>
+  <text x="155" y="190" text-anchor="middle" fill="#d6d9e0" font-size="12">belief before seeing</text>
+  <text x="155" y="208" text-anchor="middle" fill="#d6d9e0" font-size="12">this feature vector</text>
+  <text x="155" y="234" text-anchor="middle" fill="#9aa0b0" font-size="11">uniform, custom, learned from</text>
+  <text x="155" y="250" text-anchor="middle" fill="#9aa0b0" font-size="11">frequencies, or LLM-elicited</text>
+
+  <!-- Likelihood: amber = evidence -->
+  <rect x="355" y="110" width="230" height="150" rx="12" fill="none" stroke="#ffb86c" stroke-width="2.5"/>
+  <text x="470" y="140" text-anchor="middle" fill="#ffb86c" font-size="16" font-weight="bold">Likelihood</text>
+  <text x="470" y="162" text-anchor="middle" fill="#9aa0b0" font-size="12" font-style="italic">P(features | outcome)</text>
+  <text x="470" y="190" text-anchor="middle" fill="#d6d9e0" font-size="12">how typical these features</text>
+  <text x="470" y="208" text-anchor="middle" fill="#d6d9e0" font-size="12">are of each outcome</text>
+  <text x="470" y="234" text-anchor="middle" fill="#9aa0b0" font-size="11">Gaussian KDE over history,</text>
+  <text x="470" y="250" text-anchor="middle" fill="#9aa0b0" font-size="11">or an LLM over text evidence</text>
+
+  <!-- Posterior: green = result -->
+  <rect x="670" y="110" width="230" height="150" rx="12" fill="none" stroke="#50fa7b" stroke-width="2.5"/>
+  <text x="785" y="140" text-anchor="middle" fill="#50fa7b" font-size="16" font-weight="bold">Posterior</text>
+  <text x="785" y="162" text-anchor="middle" fill="#9aa0b0" font-size="12" font-style="italic">P(outcome | features)</text>
+  <text x="785" y="190" text-anchor="middle" fill="#d6d9e0" font-size="12">updated belief, as a full</text>
+  <text x="785" y="208" text-anchor="middle" fill="#d6d9e0" font-size="12">distribution not a point</text>
+  <text x="785" y="234" text-anchor="middle" fill="#9aa0b0" font-size="11">carries entropy, confidence,</text>
+  <text x="785" y="250" text-anchor="middle" fill="#9aa0b0" font-size="11">KL divergence, sampling</text>
+
+  <!-- Operators between boxes -->
+  <text x="312" y="195" text-anchor="middle" fill="#8be9fd" font-size="30" font-weight="bold">×</text>
+  <text x="627" y="195" text-anchor="middle" fill="#8be9fd" font-size="26" font-weight="bold">→</text>
+
+  <!-- Normalization note -->
+  <line x1="470" y1="285" x2="470" y2="315" stroke="#8be9fd" stroke-width="1.5" marker-end="url(#arrowCyan)" stroke-dasharray="4 3"/>
+  <rect x="245" y="318" width="450" height="60" rx="10" fill="none" stroke="#8be9fd" stroke-width="1.5"/>
+  <text x="470" y="342" text-anchor="middle" fill="#8be9fd" font-size="13" font-weight="bold">normalize by the evidence P(features)</text>
+  <text x="470" y="363" text-anchor="middle" fill="#9aa0b0" font-size="11">divide by the total so the posterior sums to 1 — Ruby does this, exactly, every time</text>
+</svg>

data/docs/assets/diagrams/kde.svg

@@ -0,0 +1,52 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 940 460" font-family="Helvetica, Arial, sans-serif">
+  <!-- Dark theme, transparent background -->
+  <defs>
+    <marker id="kdeArrow" 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>
+  </defs>
+
+  <text x="470" y="32" text-anchor="middle" fill="#f8f8f2" font-size="22" font-weight="bold">Gaussian kernel density estimation</text>
+  <text x="470" y="54" text-anchor="middle" fill="#9aa0b0" font-size="13">each stored observation of an outcome contributes a bump; the query point reads off their average</text>
+
+  <!-- Axis -->
+  <line x1="70" y1="330" x2="870" y2="330" stroke="#6272a4" stroke-width="1.5"/>
+  <text x="870" y="356" text-anchor="end" fill="#9aa0b0" font-size="12">distance from the query point, in feature space</text>
+
+  <!-- Individual kernels for outcome +1 (green) -->
+  <path d="M 150 330 Q 210 200 270 330" fill="none" stroke="#50fa7b" stroke-width="1.4" opacity="0.55"/>
+  <path d="M 200 330 Q 260 180 320 330" fill="none" stroke="#50fa7b" stroke-width="1.4" opacity="0.55"/>
+  <path d="M 250 330 Q 310 210 370 330" fill="none" stroke="#50fa7b" stroke-width="1.4" opacity="0.55"/>
+
+  <!-- Observation ticks for +1 -->
+  <circle cx="210" cy="330" r="4" fill="#50fa7b"/>
+  <circle cx="260" cy="330" r="4" fill="#50fa7b"/>
+  <circle cx="310" cy="330" r="4" fill="#50fa7b"/>
+  <text x="260" y="378" text-anchor="middle" fill="#50fa7b" font-size="12" font-weight="bold">observations with outcome +1</text>
+
+  <!-- Individual kernels for outcome -1 (red) -->
+  <path d="M 560 330 Q 620 235 680 330" fill="none" stroke="#ff5555" stroke-width="1.4" opacity="0.55"/>
+  <path d="M 620 330 Q 680 215 740 330" fill="none" stroke="#ff5555" stroke-width="1.4" opacity="0.55"/>
+
+  <circle cx="620" cy="330" r="4" fill="#ff5555"/>
+  <circle cx="680" cy="330" r="4" fill="#ff5555"/>
+  <text x="650" y="378" text-anchor="middle" fill="#ff5555" font-size="12" font-weight="bold">observations with outcome −1</text>
+
+  <!-- Query point -->
+  <line x1="280" y1="120" x2="280" y2="330" stroke="#8be9fd" stroke-width="2" stroke-dasharray="5 4"/>
+  <circle cx="280" cy="330" r="6" fill="#8be9fd"/>
+  <text x="280" y="110" text-anchor="middle" fill="#8be9fd" font-size="13" font-weight="bold">query features</text>
+
+  <!-- Density readings -->
+  <circle cx="280" cy="196" r="5" fill="none" stroke="#50fa7b" stroke-width="2"/>
+  <text x="300" y="192" fill="#50fa7b" font-size="12">high density → P(features | +1) is large</text>
+
+  <circle cx="280" cy="322" r="5" fill="none" stroke="#ff5555" stroke-width="2"/>
+  <line x1="286" y1="320" x2="430" y2="286" stroke="#ff5555" stroke-width="1" opacity="0.7"/>
+  <text x="436" y="282" fill="#ff5555" font-size="12">near zero → P(features | −1) is small</text>
+
+  <!-- Formula panel -->
+  <rect x="70" y="396" width="800" height="52" rx="10" fill="none" stroke="#bd93f9" stroke-width="1.5"/>
+  <text x="470" y="420" text-anchor="middle" fill="#bd93f9" font-size="14" font-weight="bold">P(x | outcome) = (1/n) · Σ K( ‖x − xᵢ‖ / h )   with K Gaussian</text>
+  <text x="470" y="439" text-anchor="middle" fill="#9aa0b0" font-size="11">bandwidth h sets the width of every bump: small h tracks local structure, large h smooths it away</text>
+</svg>

data/docs/assets/diagrams/llm-bayes-loop.svg

@@ -0,0 +1,58 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 920 420" font-family="Helvetica, Arial, sans-serif">
+  <!-- Dark theme, transparent background -->
+  <defs>
+    <marker id="arrow" 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="arrowAmber" 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>
+    <marker id="arrowGreen" 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="#50fa7b"/>
+    </marker>
+  </defs>
+
+  <text x="460" y="34" text-anchor="middle" fill="#f8f8f2" font-size="22" font-weight="bold">The LLM judges — Ruby computes</text>
+  <text x="460" y="56" text-anchor="middle" fill="#9aa0b0" font-size="13">division of labor between semantic judgment and probability arithmetic</text>
+
+  <!-- Evidence / context input -->
+  <rect x="30" y="120" width="200" height="90" rx="12" fill="none" stroke="#bd93f9" stroke-width="2"/>
+  <text x="130" y="150" text-anchor="middle" fill="#bd93f9" font-size="15" font-weight="bold">Natural language</text>
+  <text x="130" y="172" text-anchor="middle" fill="#d6d9e0" font-size="12">news, logs, reports,</text>
+  <text x="130" y="190" text-anchor="middle" fill="#d6d9e0" font-size="12">domain descriptions</text>
+
+  <!-- LLM box -->
+  <rect x="330" y="100" width="240" height="130" rx="12" fill="none" stroke="#ffb86c" stroke-width="2.5"/>
+  <text x="450" y="130" text-anchor="middle" fill="#ffb86c" font-size="16" font-weight="bold">LLM — the judge</text>
+  <text x="450" y="155" text-anchor="middle" fill="#d6d9e0" font-size="12">LlmPriorElicitor → P(H)</text>
+  <text x="450" y="175" text-anchor="middle" fill="#d6d9e0" font-size="12">LlmLikelihoodEstimator → P(e | H)</text>
+  <text x="450" y="203" text-anchor="middle" fill="#9aa0b0" font-size="11" font-style="italic">one independent judgment per call;</text>
+  <text x="450" y="219" text-anchor="middle" fill="#9aa0b0" font-size="11" font-style="italic">never asked to accumulate or normalize</text>
+
+  <!-- Bayes engine box -->
+  <rect x="660" y="100" width="230" height="130" rx="12" fill="none" stroke="#50fa7b" stroke-width="2.5"/>
+  <text x="775" y="130" text-anchor="middle" fill="#50fa7b" font-size="16" font-weight="bold">Ruby — the engine</text>
+  <text x="775" y="155" text-anchor="middle" fill="#d6d9e0" font-size="12">Prior × Likelihood → Posterior</text>
+  <text x="775" y="175" text-anchor="middle" fill="#d6d9e0" font-size="12">normalize · clamp · entropy · KL</text>
+  <text x="775" y="203" text-anchor="middle" fill="#9aa0b0" font-size="11" font-style="italic">exact arithmetic, no anchoring,</text>
+  <text x="775" y="219" text-anchor="middle" fill="#9aa0b0" font-size="11" font-style="italic">no double-counting</text>
+
+  <!-- Posterior output -->
+  <rect x="360" y="300" width="330" height="80" rx="12" fill="none" stroke="#8be9fd" stroke-width="2"/>
+  <text x="525" y="330" text-anchor="middle" fill="#8be9fd" font-size="15" font-weight="bold">Posterior belief</text>
+  <text x="525" y="352" text-anchor="middle" fill="#d6d9e0" font-size="12">MAP · confidence · information gain · samples</text>
+
+  <!-- Arrows -->
+  <line x1="230" y1="165" x2="322" y2="165" stroke="#ffb86c" stroke-width="2" marker-end="url(#arrowAmber)"/>
+  <text x="276" y="152" text-anchor="middle" fill="#9aa0b0" font-size="11">prompt</text>
+
+  <line x1="570" y1="165" x2="652" y2="165" stroke="#50fa7b" stroke-width="2" marker-end="url(#arrowGreen)"/>
+  <text x="611" y="152" text-anchor="middle" fill="#9aa0b0" font-size="11">numbers</text>
+
+  <line x1="775" y1="230" x2="700" y2="298" stroke="#8be9fd" stroke-width="2" marker-end="url(#arrow)"/>
+
+  <!-- Feedback loop: posterior becomes next prior -->
+  <path d="M 360 345 C 150 345, 130 300, 130 218" fill="none" stroke="#8be9fd" stroke-width="2" stroke-dasharray="6 5" marker-end="url(#arrow)"/>
+  <text x="180" y="330" text-anchor="middle" fill="#8be9fd" font-size="11" font-style="italic">posterior becomes the next prior</text>
+  <text x="180" y="346" text-anchor="middle" fill="#8be9fd" font-size="11" font-style="italic">as new evidence arrives</text>
+</svg>

data/docs/assets/diagrams/provider-resolution.svg

@@ -0,0 +1,77 @@
+<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="prArrow" 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="prArrowGreen" 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="#50fa7b"/>
+    </marker>
+    <marker id="prArrowRed" 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="#ff5555"/>
+    </marker>
+  </defs>
+
+  <text x="480" y="32" text-anchor="middle" fill="#f8f8f2" font-size="22" font-weight="bold">Provider resolution — local first</text>
+  <text x="480" y="54" text-anchor="middle" fill="#9aa0b0" font-size="13">LlmSupport.resolve_provider, and the two ways a local run quietly becomes a cloud run</text>
+
+  <!-- Step 1: env override -->
+  <rect x="330" y="80" width="300" height="60" rx="10" fill="none" stroke="#f1fa8c" stroke-width="2"/>
+  <text x="480" y="105" text-anchor="middle" fill="#f1fa8c" font-size="13" font-weight="bold">SQA_BI_LLM_PROVIDER set?</text>
+  <text x="480" y="126" text-anchor="middle" fill="#9aa0b0" font-size="11">explicit wins — lms | apfel | cloud</text>
+
+  <path d="M 480 140 L 480 176" fill="none" stroke="#8be9fd" stroke-width="1.6" marker-end="url(#prArrow)"/>
+  <text x="500" y="163" fill="#9aa0b0" font-size="11">no</text>
+
+  <!-- Step 2: LM Studio probe -->
+  <rect x="330" y="178" width="300" height="72" rx="10" fill="none" stroke="#8be9fd" stroke-width="2"/>
+  <text x="480" y="203" text-anchor="middle" fill="#8be9fd" font-size="13" font-weight="bold">GET localhost:1234/v1/models</text>
+  <text x="480" y="223" text-anchor="middle" fill="#d6d9e0" font-size="11">LM Studio — ruby_llm-providers-lms</text>
+  <text x="480" y="240" text-anchor="middle" fill="#9aa0b0" font-size="10">1 second timeout</text>
+
+  <path d="M 480 250 L 480 286" fill="none" stroke="#8be9fd" stroke-width="1.6" marker-end="url(#prArrow)"/>
+  <text x="500" y="273" fill="#9aa0b0" font-size="11">no answer</text>
+
+  <!-- Step 3: apfel probe -->
+  <rect x="330" y="288" width="300" height="72" rx="10" fill="none" stroke="#8be9fd" stroke-width="2"/>
+  <text x="480" y="313" text-anchor="middle" fill="#8be9fd" font-size="13" font-weight="bold">GET 127.0.0.1:11434/v1/models</text>
+  <text x="480" y="333" text-anchor="middle" fill="#d6d9e0" font-size="11">Apfel — Apple Foundation Models</text>
+  <text x="480" y="350" text-anchor="middle" fill="#9aa0b0" font-size="10">1 second timeout</text>
+
+  <path d="M 480 360 L 480 396" fill="none" stroke="#ff5555" stroke-width="1.6" marker-end="url(#prArrowRed)"/>
+  <text x="500" y="383" fill="#9aa0b0" font-size="11">no answer</text>
+
+  <!-- Cloud fallback -->
+  <rect x="330" y="398" width="300" height="72" rx="10" fill="none" stroke="#ff5555" stroke-width="2.5"/>
+  <text x="480" y="423" text-anchor="middle" fill="#ff5555" font-size="13" font-weight="bold">cloud — CLOUD_DEFAULT_MODEL</text>
+  <text x="480" y="443" text-anchor="middle" fill="#d6d9e0" font-size="11">claude-haiku-4-5, needs an API key</text>
+  <text x="480" y="460" text-anchor="middle" fill="#9aa0b0" font-size="10">this fallback is silent — call current_resolution to see it</text>
+
+  <!-- Success branches to the right -->
+  <path d="M 630 214 L 740 214" fill="none" stroke="#50fa7b" stroke-width="1.6" marker-end="url(#prArrowGreen)"/>
+  <path d="M 630 324 L 740 324" fill="none" stroke="#50fa7b" stroke-width="1.6" marker-end="url(#prArrowGreen)"/>
+
+  <rect x="742" y="186" width="200" height="56" rx="10" fill="none" stroke="#50fa7b" stroke-width="2"/>
+  <text x="842" y="210" text-anchor="middle" fill="#50fa7b" font-size="13" font-weight="bold">:lms</text>
+  <text x="842" y="230" text-anchor="middle" fill="#9aa0b0" font-size="10">choose_local_model picks qwen</text>
+
+  <rect x="742" y="296" width="200" height="56" rx="10" fill="none" stroke="#50fa7b" stroke-width="2"/>
+  <text x="842" y="320" text-anchor="middle" fill="#50fa7b" font-size="13" font-weight="bold">:apfel</text>
+  <text x="842" y="340" text-anchor="middle" fill="#9aa0b0" font-size="10">on-device Apple model</text>
+
+  <!-- The two gotchas -->
+  <rect x="20" y="150" width="290" height="230" rx="12" fill="none" stroke="#ffb86c" stroke-width="2"/>
+  <text x="165" y="176" text-anchor="middle" fill="#ffb86c" font-size="13" font-weight="bold">Why the probe fails</text>
+
+  <text x="40" y="204" fill="#ffb86c" font-size="12" font-weight="bold">1 — the server is off</text>
+  <text x="40" y="224" fill="#d6d9e0" font-size="11">The LM Studio desktop app being</text>
+  <text x="40" y="240" fill="#d6d9e0" font-size="11">open is not the same as its HTTP</text>
+  <text x="40" y="256" fill="#d6d9e0" font-size="11">server running.</text>
+  <text x="40" y="276" fill="#8be9fd" font-size="11" font-family="monospace">lms status</text>
+  <text x="40" y="293" fill="#8be9fd" font-size="11" font-family="monospace">lms server start</text>
+
+  <text x="40" y="322" fill="#ffb86c" font-size="12" font-weight="bold">2 — no chat model loaded</text>
+  <text x="40" y="341" fill="#d6d9e0" font-size="11">Embedding and OCR models are</text>
+  <text x="40" y="357" fill="#d6d9e0" font-size="11">rejected, so a server offering only</text>
+  <text x="40" y="373" fill="#d6d9e0" font-size="11">those resolves to no model at all.</text>
+</svg>

data/docs/assets/js/mathjax.js

@@ -0,0 +1,18 @@
+/* MathJax configuration for SQA::BI documentation */
+
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.typesetPromise()
+})

data/docs/development.md

@@ -0,0 +1,164 @@
+# Development
+
+## Setup
+
+```bash
+cd ~/sandbox/git_repos/madbomber/projects/sqa_project/sqa-bi
+bundle install
+bundle exec rake test
+```
+
+The workspace uses [asgard](https://github.com/MadBomber/asgard) `.loki` task
+files. Run `asgard help` from any repo for the available commands rather than
+memorizing raw `rake`/`bundle` invocations.
+
+## Testing
+
+```bash
+asgard test                              # or: bundle exec rake test
+ruby -Ilib:test test/llm_support_test.rb # a single file
+```
+
+Minitest, with SimpleCov. Current state: **77 tests, 148 assertions, 0
+failures, ~86% line coverage.**
+
+### Rules the suite enforces
+
+**No test touches a real provider.** Both LLM classes accept an injectable
+`chat:`, and `test/test_helper.rb` supplies a `FakeChat` that returns canned
+content and records the prompt it was given. Any test that would make a network
+call is a bug.
+
+**Environment-dependent tests must be hermetic.** `LlmSupport.env_model` reads
+`SQA_BI_LLM_MODEL` and `BI_LLM_MODEL`, so tests that exercise it use the
+`without_env` helper to clear and restore them. A developer with either variable
+exported must still get a green suite.
+
+**Every method is testable in isolation.** `LlmSupport` is entirely
+`module_function`. `build_prompt`, `prior_from_response` and
+`likelihoods_from_response` are public and pure so prompt wording and parsing
+can be tested directly. Even the examples follow this — `UI` methods return
+Strings and print nothing; `ExampleBundle.gemfile_path` is pure and unit tested.
+
+## Quality gates
+
+```bash
+asgard quality     # tests + coverage, Flog, Flay, Reek
+asgard rubocop
+asgard rubocop_fix
+```
+
+| Gate | Threshold |
+|---|---|
+| **Tests** | all pass, with SimpleCov coverage |
+| **Flog** | warn ≥ 20, fail ≥ 50 (per method) |
+| **Flay** | fail on structural duplication with mass ≥ 50 |
+| **Reek** | fail only on files that are **new or worsened** vs the baseline |
+| **RuboCop** | zero offenses |
+
+### RuboCop is shared, don't edit it here
+
+`.rubocop.yml` is generated from the workspace's `.rubocop.yml.common`. Edit
+that file and run `asgard sync_rubocop`; a local edit is overwritten at the next
+sync.
+
+### Reek runs against a baseline
+
+`.quality/reek_baseline.txt` grandfathers **11** smells across 5 files. All are
+deliberate:
+
+- **FeatureEnvy** in the `reduce`-based `Prior#entropy`, `Posterior#entropy`,
+  `#kl_divergence_from_prior`, and `Likelihood#euclidean_distance` — these are
+  numeric folds over a local, not misplaced methods.
+- **TooManyStatements** in `LlmSupport.configure_ruby_llm` and
+  `Posterior#compute_posterior`.
+- **ControlParameter** in `LlmSupport.local_api_base` and `.resolution_label` —
+  small lookup/format functions where branching on the argument *is* the
+  function.
+- **BooleanParameter / ControlParameter** on `TimeSeriesPredictor#initialize`
+  (`update_prior:`) and `#reset!` (`keep_prior:`) — API shape, not accidents.
+
+Regenerate with `asgard reek_baseline` after a genuine improvement. The gate is
+baseline-aware by design: the point is to stop *regressions*, not to reach zero.
+
+!!! warning "If you hand-edit the baseline"
+    Reek prints `1 warning:` — **singular** — for single-smell files. Grepping
+    for `warnings:` silently drops them and produces a baseline that fails the
+    gate. Derive counts from `Reek::Examiner`, the way `rake reek_check` does.
+
+`Posterior#summary` sits at Flog 21.2 — above the warn threshold, below the fail
+threshold. It is a formatting heredoc.
+
+## Architecture rules
+
+**`sqa-bi` is a leaf.** No runtime dependencies, and deliberately no dependency
+on `sqa`. It sits beside `sqa-tai` so that `sqa` can depend on *it*. Adding a
+`sqa` dependency to the gemspec inverts the graph and creates a cycle the moment
+`sqa` picks this gem up.
+
+**The core math stays domain-agnostic.** It knows nothing about markets. Keep it
+that way; market-facing code belongs in `sqa` or in the examples.
+
+**`ruby_llm` stays lazily required** inside `LlmSupport.build_chat`, and stays a
+development dependency. The library must load, and KDE must work, without it.
+
+**The LLM judges, Ruby computes.** Any change to `LlmPriorElicitor` or
+`LlmLikelihoodEstimator` must preserve the split: the model supplies isolated
+judgments, Ruby does every piece of arithmetic.
+
+## Documentation
+
+```bash
+mkdocs serve    # live reload at http://127.0.0.1:8000
+mkdocs build    # static site into site/ (gitignored)
+```
+
+MkDocs with the Material theme, dark by default.
+
+Diagrams are hand-authored SVG in `docs/assets/diagrams/`, following the
+project convention: **dark theme, transparent background, colour used to
+distinguish function** — purple for prior/belief, amber for likelihood/evidence,
+green for posterior/result, cyan for flow and structure, red for failure paths.
+`docs/assets/css/custom.css` puts a dark plate behind them in light mode.
+
+## Bundle mode
+
+The workspace root `.envrc` reads `.bundle_mode` and exports `BUNDLE_GEMFILE`:
+
+| Mode | Gemfile | Resolves |
+|---|---|---|
+| `dev` (default) | `Gemfile.local` | sibling checkouts via `path:` |
+| `prod` | `Gemfile` | released gems only |
+
+Switch with `asgard dev` / `asgard prod` at the workspace root. A component's
+`.envrc` must **not** re-export `BUNDLE_GEMFILE` — that would silently override
+the workspace-wide mode.
+
+!!! note "It is exported as a relative name"
+    Which means `bundle exec` only resolves correctly from a repo root. Running
+    from a subdirectory — `examples/`, say — fails to find the Gemfile and
+    silently falls back to the global gemset. `examples/example_bundle.rb`
+    works around it for the demos; be aware of it elsewhere.
+
+## Commit conventions
+
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) — see
+`COMMITS.md` in the repo.
+
+## Open threads
+
+Tracked in `decision_support_techniques.md` and
+[Exploration Notes](EXPLORATION.md):
+
+- **Multi-horizon prediction** (k = 1…10) sharing strength across horizons
+  rather than fitting each independently. `TimeSeriesPredictor` is
+  single-horizon today, and adjacent horizons are strongly correlated.
+- **A Laya sidecar** as an alternative likelihood backend behind `LlmSupport`'s
+  provider dispatch, benchmarked on latency and calibration (ECE).
+- **`eps` / LightGBM as a benchmark** to score the posterior against — not as a
+  replacement engine.
+- **Research JEV properly** before it influences any design decision.
+
+Read the log before proposing a different inference engine; the tree-ensemble
+and typed-decision routes were each evaluated there and set aside for recorded
+reasons.

data/docs/examples/index.md

@@ -0,0 +1,198 @@
+# Examples
+
+Five runnable demos in [`examples/`](https://github.com/MadBomber/sqa-bi/tree/main/examples).
+Each prints a narrated walkthrough rather than bare numbers.
+
+```bash
+ruby examples/01_coin_flip.rb
+ruby examples/02_time_series_prediction.rb
+ruby examples/03_stock_market_prediction_v2.rb
+ruby examples/04_llm_elicited_prior.rb
+ruby examples/05_llm_likelihood_diagnosis.rb
+```
+
+They also run directly by shebang (`./01_coin_flip.rb`) — `examples/common.rb`
+activates the bundle first, which matters more than it sounds. See
+[Running them](#running-them) below.
+
+---
+
+## 01 — Coin flip
+
+**The mechanics, stripped to the minimum.** A one-dimensional feature (observed
+heads-rate) mapped onto three outcomes: fair, leans heads, heavily heads.
+
+Establishes the core loop — train, predict, read the distribution — with nothing
+domain-specific in the way. Ends by sampling from the posterior to show what
+residual uncertainty looks like as a tally:
+
+```
+    0    38   38.0%  ███████████████░░░░░░░░░  Fair coin
+    1    60   60.0%  ████████████████████████  Leans heads
+    2     2    2.0%  █░░░░░░░░░░░░░░░░░░░░░░░  Heavily heads
+```
+
+**Read it for:** the shape of the API, and why confidence rises away from
+category boundaries.
+
+---
+
+## 02 — Time series prediction
+
+**Synthetic trends with known ground truth.** Generates trending, sideways and
+reversing series, extracts features, trains, and predicts on held-out data.
+
+Because the true outcome is known by construction, this is the one place you can
+see the predictor being *right* and *wrong* without arguing about the data.
+
+**Read it for:** feature extraction from a sequence, and how entropy behaves as
+a series becomes more or less ambiguous.
+
+---
+
+## 03 — Stock market prediction
+
+**Real OHLCV data through the `sqa` gem.** Predicts the next day's close band
+from five delta features — close change, volume change, and changes in SMA(20),
+RSI(14) and EMA(12).
+
+```
+Loading T historical data...
+Loaded 6761 days of T data
+Date range: 1999-11-01 to 2026-09-18
+
+Generated 6739 feature vectors
+Training set: 5391 samples
+Test set: 1348 samples
+```
+
+It prints a confusion matrix, and the matrix is the point:
+
+```
+Actual \ Predicted:     0   1   2   3   4
+----------------------------------------
+ 0 (big_down   ):    0   2   5   3   0
+ 1 (small_down ):    0  27 343  69   0
+ 2 (sideways   ):    0  28 353  62   0
+ 3 (small_up   ):    0  51 327  70   0
+ 4 (big_up     ):    0   0   7   1   0
+```
+
+!!! warning "This demo is honest about failing"
+    Columns 0 and 4 are empty — the extreme bands hold under 1% of training
+    samples each, so the KDE has too few neighbours to ever favor them. The
+    model collapses onto the middle three bands and mostly predicts "sideways".
+
+    That is exactly what [Tuning](../guide/tuning.md) warns about, shown rather
+    than described. Next-day equity direction from five TA deltas is close to
+    unpredictable, and a method that reports its uncertainty honestly will tell
+    you so instead of manufacturing a signal.
+
+**Requires the `sqa` gem**, which `sqa-bi` does not depend on. Run it in dev
+bundle mode (`asgard dev` at the workspace root).
+
+**Read it for:** delta-based feature engineering, chronological train/test
+splitting, and what class imbalance looks like from the inside.
+
+---
+
+## 04 — LLM-elicited prior
+
+**Domain knowledge as a prior.** Five training observations — far too few for
+KDE — plus a paragraph of market context handed to a language model.
+
+```
+LLM: lms — qwen/qwen3.8-27b at http://localhost:1234/v1
+
+LLM-elicited prior: Prior(-2: 0.000, -1: 0.020, 0: 0.080, 1: 0.350, 2: 0.550)
+Prior entropy: 1.409 bits (uniform would be 2.322)
+
+With UNIFORM prior (data only)
+Posterior(-2: 0.000, -1: 0.139, 0: 0.358, 1: 0.358, 2: 0.144)
+Confidence:  19.9%
+
+With LLM-ELICITED prior (knowledge + data)
+Posterior(-2: 0.000, -1: 0.040, 0: 0.256, 1: 0.576, 2: 0.129)
+Confidence:  34.2%
+```
+
+The data-only posterior is a dead tie between "sideways" and "mild uptrend".
+The elicited prior breaks it.
+
+**Read it for:** [prior elicitation](../llm/prior-elicitation.md) in practice,
+and the side-by-side that shows what the prior actually bought.
+
+---
+
+## 05 — LLM likelihood diagnosis
+
+**Sequential Bayesian updating over textual evidence.** A production outage,
+three competing hypotheses, five pieces of evidence arriving in order.
+
+```
+LLM: lms — qwen/qwen3.8-27b at http://localhost:1234/v1
+
+Initial belief:   bad_deploy 33.3%   database 33.3%   network 33.3%
+
+Evidence 1: HTTP 500 error rate jumped from 0.1% to 8% at 14:04, two
+            minutes after the deploy finished.
+  P(e|H): bad_deploy=0.95  database=0.60  network=0.10
+  gain: 0.351 bits    bad_deploy 57.6%  database 36.4%  network 6.1%
+
+...
+
+Final diagnosis: network at 99.7% confidence
+```
+
+Evidence 1 looks damning for the deploy. Because likelihoods are clamped away
+from 0 and 1, Bayes never fully commits — and evidence 3–5 cleanly reverse the
+belief.
+
+**Read it for:** [likelihood estimation](../llm/likelihood-estimation.md),
+[chained updates](../guide/posterior.md#chaining-updates-across-several-pieces-of-evidence),
+and per-update information gain identifying which facts mattered.
+
+---
+
+## Supporting files
+
+**`common.rb`** — activates the bundle, loads the library, includes the
+`SQA::BI` namespace, and provides the `UI` module of terminal helpers (banners,
+bars, distribution charts). Every `UI` method returns a String and prints
+nothing, so each is testable in isolation.
+
+**`example_bundle.rb`** — resolves which Gemfile to activate. Pure, and unit
+tested.
+
+**`pure_ruby_indicators.rb`** — dependency-free SMA / EMA / RSI so the demos
+need no `sqa-tai` build. Production code should use `sqa-tai`, which wraps the
+real TA-Lib and provides 136+ indicators.
+
+## Running them
+
+Prefer `bundle exec`, or run them directly — both work:
+
+```bash
+bundle exec ruby examples/04_llm_elicited_prior.rb
+cd examples && ./04_llm_elicited_prior.rb
+```
+
+??? info "Why the shebang path needs `example_bundle.rb`"
+    The workspace direnv exports `BUNDLE_GEMFILE` as a **bare relative name**
+    (`Gemfile` or `Gemfile.local`, per `asgard dev` / `asgard prod`) so each
+    repo picks up its own. Bundler resolves that against the current directory
+    — which, for a demo launched by its shebang, is `examples/`, not the repo
+    root. The lookup fails, the bundle is never activated, and RubyGems
+    resolves against the entire rbenv gemset instead.
+
+    That matters because `json 3.x` then wins, and `ruby_llm 2.0` requires
+    `json < 3`. The LLM demos die at `require 'ruby_llm'` with an opaque
+    `Gem::ConflictError` that says nothing about bundles.
+
+    `ExampleBundle.gemfile_path` anchors the relative name to the repo root
+    before `require 'bundler/setup'`, which fixes it.
+
+The two LLM demos need a provider. With no local server running they fall
+through to cloud silently — see
+[Providers and Local Models](../llm/providers.md), and note that they print
+their resolved provider on the first line for exactly this reason.