Home

Statistikles

A neurosymbolic statistical analysis assistant where the LLM never touches a number.

Statistikles lets you ask statistical questions in plain English and get answers you can trust. A language model reads your question and picks the right tool; Julia performs every calculation. The number in the reply is never invented by the model — it is computed by deterministic, tested code and audited before you ever see it.

The project's own name for a plausible-sounding but fabricated statistic is a "mollock". Statistikles exists to make mollocks structurally impossible.

---

What it is

Statistikles is a Kautz Type‑1 neurosymbolic system — neural and symbolic components run side by side across a defined, auditable boundary (see README.adoc and src/Statistikles.jl):

Component	Role	Implementation
Neural (LLM)	Understands the natural‑language question, routes it to a tool, explains the result in plain English. Computes nothing.	LM Studio, via src/tools/lmstudio.jl
Symbolic (Julia)	Performs all mathematics and statistics. Every result is exact and deterministic.	~41 modules in src/stats/, dispatched by src/tools/executor.jl

The interface layer is registered in src/tools/definitions.jl, which declares 29 function‑calling tool schemas for the model. Under the hood, src/tools/executor.jl routes 55 tool names to verified Julia functions.

The neurosymbolic premise

Traditional LLM statistics fail in a specific way: the model recalls or estimates a p‑value, an effect size, or a mean, and states it with confidence. Sometimes it is right; often it is a mollock. Statistikles removes the model from the computation path entirely:

You: "Is there a significant difference between these two groups?"
     │
     ▼  Natural-language understanding (neural)
LLM routes to: t_test_independent(group1, group2)
     │
     ▼  Symbolic computation (Julia)
Julia computes: t = 2.847, df = 38, p = 0.007, Cohen's d = 0.90
     │
     ▼  Natural-language generation (neural)
LLM explains: "Yes — a statistically significant difference
              (t(38) = 2.847, p = .007), with a large effect (d = 0.90)."

Every number in that answer came from Julia. The model only phrased it.

The enforced no‑fabrication guarantee

The promise "no number is ever produced by the LLM" is enforced in code, not just stated in a prompt. After the model writes its reply, src/tools/guardrail.jl runs validate_numeric_provenance():

• It harvests every numeric value that actually flowed out of the symbolic tool calls (collect_numbers).
• It extracts every numeric literal from the model's prose (extract_numeric_tokens).
• Each prose number must trace to a recorded tool result — within a relative tolerance (rtol = 1e-6), or as a sign flip, or as a ÷100 / ×100 percentage variant, or after display‑rounding — or match a number the user supplied, or be a small structural integer in 0..12 (degrees of freedom, group counts, and the like).
• Any number that matches nothing is an orphan: a likely mollock.

The guardrail never silently rewrites the model's text. enforce_numeric_boundary! (in src/tools/chat.jl) does one retry — asking the model to restate using only tool‑derived numbers — and if orphans remain it appends a visible UNVERIFIED NUMBERS — POSSIBLE MOLLOCK warning block listing them. Orphans are flagged, never fabricated.

See The-No-Fabrication-Guarantee for the full mechanism.

Quick start

Requires Julia 1.10+. LM Studio (default localhost:1234) is needed for the chat interface; the offline demo runs without it.

julia --project=. -e 'using Pkg; Pkg.instantiate()'
julia --project=. -e 'using Statistikles; main()'

Run the offline examples (no LLM required):

julia --project=. -e 'using Statistikles; run_examples()'

Full details in Installation and Usage-and-Examples.

A note on honesty

Statistikles is careful about what it claims:

• It is not "formally verified statistics." The Agda proofs in proofs/ type‑check under agda --safe, but they are stated over the natural numbers (ℕ) and are discrete proxies for the real‑valued (Float64) statistical targets, which remain open. The Zig FFI in ffi/zig compiles and has CI, but its entry points are placeholders not yet backed by the Julia core. Both are tracked as experimental — see Experimental-Surfaces.
• The guarantee it does enforce is the numeric‑provenance boundary above, backed by tests in test/guardrail_test.jl.

Where to go next

I want to…	Page
Understand the neural + symbolic split and the request flow	Architecture
Read how the no‑fabrication guarantee works	The-No-Fabrication-Guarantee
Install and run it	Installation · Usage-and-Examples
Learn the chat interface, commands, and example queries	Usage-and-Examples
Browse the available statistical methods and the src/stats/ modules	Statistical-Functions-Reference
Understand tool definitions, dispatch, and the data pipeline	Architecture
Dig into the provenance guardrail internals	The-No-Fabrication-Guarantee
Contribute code	Development-Guide
Run and understand the test suite	Testing-and-Validation
Learn about the Zig FFI and Agda proofs	Experimental-Surfaces
Review the security posture and threat model	Security-and-Threat-Model
See the roadmap and production-readiness status	Roadmap-and-Production-Readiness
Read common questions	FAQ
Cut a release	Release-Process

---

Statistikles is authored by Jonathan D.A. Jewell (hyperpolymath). Code is licensed MPL‑2.0; documentation CC‑BY‑SA‑4.0.