Skip to content

Commit c766d92

Browse files
hyperpolymathhyperpolymath
committed
Add sponsor badge
1 parent 49324d0 commit c766d92

1 file changed

Lines changed: 206 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath)
2+
3+
= Aspasia — Independent Neurosymbolic Statistical Auditor
4+
:author: Jonathan D.A. Jewell
5+
:email: j.d.a.jewell@open.ac.uk
6+
:license: MPL-2.0
7+
:toc:
8+
9+
== The Name
10+
11+
**Aspasia of Miletus** (~470-400 BCE) taught Socrates the art of rhetoric and
12+
dialectic. Plato credits her in the _Menexenus_; Plutarch describes her as a
13+
thinker consulted on matters of state. She didn't cross-examine for sport —
14+
she sharpened others' reasoning constructively.
15+
16+
This system is named for her because it corrects the corrector. StatistEase
17+
uses Socratic method (LLM routes questions, Julia answers). Aspasia audits
18+
that entire process — the teacher checking the student's work. And like her
19+
namesake, Aspasia is not an annoying gadfly. She is a wise advisor who helps
20+
you feel _more confident_ in your results, not less.
21+
22+
== Why Does This Exist?
23+
24+
StatistEase computes statistics using Julia. An LLM routes questions to Julia
25+
functions and explains the results. No neural numbers — good.
26+
27+
But three problems remain:
28+
29+
1. **Did Julia compute correctly?** Software has bugs. Numerical libraries
30+
have edge cases. A single implementation is a single point of failure.
31+
2. **Was this the right test?** The LLM chose a t-test. Should it have been
32+
Mann-Whitney? The LLM doesn't _know_ — it pattern-matches. It might be
33+
right. It might be confidently wrong.
34+
3. **Is the explanation accurate?** The LLM says "large effect size" but
35+
Cohen's d is 0.35. That's small-to-medium. The number was correct; the
36+
_interpretation_ was not.
37+
38+
Aspasia solves all three by providing an **independent neurosymbolic audit**
39+
from a completely separate codebase, in a completely different language, using
40+
a completely different reasoning engine.
41+
42+
== Why Octave? Why Not Julia?
43+
44+
This is the most important design decision in the project, and it is *not*
45+
overcomplicated — it is the *minimum* necessary for genuine independence:
46+
47+
[cols="1,1,1"]
48+
|===
49+
|Property |StatistEase (Julia) |Aspasia (GNU Octave)
50+
51+
|Numerical backend |OpenBLAS |LAPACK/BLAS (system)
52+
|Sorting algorithm |Julia's QuickSort |Octave's std::sort
53+
|Statistical library |StatsBase.jl |Octave statistics package
54+
|Floating-point path |Julia's LLVM codegen |GCC/gfortran codegen
55+
|Reasoning engine |LLM tool calling |Prolog + DeepProbLog
56+
|Developer community |Scientific computing |Engineering + applied maths
57+
|===
58+
59+
If both systems produce the same answer via **different code paths**, that
60+
answer is far more trustworthy than either system alone. If they disagree,
61+
that disagreement is **valuable information** — it reveals either a bug or
62+
a genuine numerical sensitivity.
63+
64+
Using the same language would mean the same library, the same bugs, the same
65+
blind spots. That is not independence. That is redundancy.
66+
67+
This also attracts **different developers**. Julia people and Octave/MATLAB
68+
people come from different disciplines, think differently about numerical
69+
problems, and catch different classes of bugs. Two independent communities
70+
competing toward the same goal — correctness — makes both systems better.
71+
72+
== Architecture
73+
74+
```
75+
StatistEase Aspasia
76+
┌────────────────────┐ ┌────────────────────┐
77+
│ Julia computation │ │ Octave recompute │
78+
│ (the numbers) │──── JSON ───►│ (same data, diff │
79+
│ │ transaction│ code path) │
80+
└────────┬───────────┘ └────────┬───────────┘
81+
│ │
82+
│ ┌────────▼───────────┐
83+
│ │ Prolog ontology │
84+
│ │ (was this the │
85+
│ │ RIGHT test?) │
86+
│ └────────┬───────────┘
87+
│ │
88+
│ ┌────────▼───────────┐
89+
│ │ Interpretation │
90+
│ │ audit (does the │
91+
│ │ explanation match │
92+
│ │ the numbers?) │
93+
│ └────────┬───────────┘
94+
│ │
95+
▼ ▼
96+
┌────────────────────────────────────────────────────────┐
97+
│ USER SEES BOTH │
98+
│ Result: t(38) = 2.847, p = .007, d = 0.90 │
99+
│ Audit: VERIFIED — computation, test selection, and │
100+
│ interpretation all check out. │
101+
└────────────────────────────────────────────────────────┘
102+
```
103+
104+
== The Three Audit Phases
105+
106+
=== Phase 1: Numerical Verification (Octave)
107+
108+
"Did the computation produce the correct numbers?"
109+
110+
Aspasia independently recomputes every statistical result using GNU Octave.
111+
Different language, different BLAS, different floating-point code paths. If
112+
the results match within tolerance (1e-10), the numbers are verified.
113+
114+
=== Phase 2: Ontological Reasoning (Prolog/DeepProbLog)
115+
116+
"Was this the right test to run?"
117+
118+
A Prolog knowledge base encodes Stevens' measurement scales, test prerequisites,
119+
assumption requirements, and nonparametric alternatives. DeepProbLog extends this
120+
with probabilistic confidence.
121+
122+
This is genuinely neurosymbolic — the probabilities can be learned from data
123+
(neural) while the logical structure is fixed (symbolic).
124+
125+
=== Phase 3: Interpretation Audit (Prolog + Octave)
126+
127+
"Does the LLM's explanation accurately represent the result?"
128+
129+
Cross-references effect size labels against Cohen's conventions, checks for
130+
p-value misinterpretation (ASA 2016 statement), detects significance inflation
131+
with large N, and flags missing assumption discussions.
132+
133+
== Governance Model
134+
135+
Aspasia operates as an **AUDITOR**, not a gatekeeper:
136+
137+
- It NEVER modifies StatistEase output
138+
- It NEVER prevents computation
139+
- It ALWAYS explains WHY it raises a concern
140+
- It tracks its own accuracy (precision and recall of challenges)
141+
- It learns from user feedback (Logtalk knowledge base)
142+
143+
== What Happens When They Disagree?
144+
145+
A disagreement between two independent systems is not a failure — it is
146+
*information*. The magnitude, location, and nature of the disagreement
147+
tells you something about your data that neither system alone could reveal.
148+
149+
=== Resolution Ladder (automated, 6 steps)
150+
151+
Before asking a human, Aspasia runs a systematic resolution protocol:
152+
153+
[cols="1,3,1"]
154+
|===
155+
|Step |Method |Confidence
156+
157+
|1 |**NIST StRD reference values** — certified answers to 15+ digits (McCullough & Wilson 1999) |Definitive
158+
|2 |**Arbitrary precision recomputation** — Neumaier compensated summation at extended precision |High
159+
|3 |**Interval arithmetic** — guaranteed enclosures; if both values fall inside, they're compatible |High
160+
|4 |**Perturbation analysis** — jitter inputs by 1 ULP; if output swings wildly, the problem is ill-conditioned and *neither answer is reliable* |Diagnostic
161+
|5 |**Symbolic verification** — compute exact answer via sorted summation or CAS (Maxima) |Definitive
162+
|6 |**Escalate to human** — with FULL evidence from steps 1-5 and both systems' working |Last resort
163+
|===
164+
165+
Most disagreements resolve at steps 1-3. Step 4 is particularly valuable:
166+
when it triggers, it means the data itself doesn't support the precision being
167+
claimed — that's a finding about the research, not a bug in the software.
168+
169+
=== Three-Body Governance
170+
171+
When the resolution ladder exhausts automated methods:
172+
173+
- **StatistEase** computes (Julia)
174+
- **Aspasia** audits (Octave + Prolog)
175+
- **echidna** arbitrates (formal proofs via GraphQL)
176+
177+
If echidna cannot resolve the dispute (because it's a judgment call, not a
178+
mathematical fact), the system escalates to the human with full evidence
179+
from all three systems. It says:
180+
181+
> "We tried our best but we are coming up against conflicts. Here is
182+
> everything we checked, everything we found, and what each system thinks.
183+
> You need to decide."
184+
185+
This is honest. It is more useful than silently picking one answer.
186+
187+
== Requirements
188+
189+
* **GNU Octave 8+** with the `statistics` package
190+
* **SWI-Prolog 9+** (for ontological reasoning)
191+
* **Logtalk 3+** (for knowledge base management)
192+
* Optional: **DeepProbLog** (for probabilistic logic)
193+
194+
== Quick Start
195+
196+
```bash
197+
octave --eval "pkg install -forge statistics"
198+
octave --path src/verification:src/audit:src/interface \
199+
--eval "audit_from_json('/path/to/transaction.json')"
200+
```
201+
202+
== License
203+
204+
MPL-2.0 (Palimpsest License)
205+
206+
Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>

0 commit comments

Comments
 (0)