int-llm-sql

Bit-exact, integer-only microgpt inference in one SQLite shell script.

This is an actual transformer running in SQL—not a text-to-SQL tool. The standalone microgpt.sql loads a binary model, performs the complete forward pass and autoregressive sampling loop, and verifies its own raw logits and generated bytes against pinned regression checksums.

No stored procedures, user-defined functions, loadable extensions, floating-point arithmetic, network access, or helper process participates in the run. The only non-portable feature is the sqlite3 shell's readfile() helper, called once for the committed model.

Quick start

Run from the repository root:

sqlite3 :memory: < microgpt.sql

The release is tested with SQLite 3.51.0. A compatible shell needs recursive CTEs, generated columns, window functions, ordered aggregate arguments, and readfile(). You can probe the last requirement with:

sqlite3 :memory: "SELECT length(readfile('model/uniform-f12.mgw'));"
# 115576

A complete run takes a few seconds on a modern laptop and prints 20 generated names. The output begins and ends as follows (abbreviated; the complete transcript is expected_output.txt):

LANE sql sample_hash=0f6b22da7c9b715b logits_hash=0610f72f01c199cb steps=122
SAMPLE 01 kayla
...
SAMPLE 20 karin
SQL_GATE=PASS

The names are generated, not pasted. Both FNV-1a regression checksums and the 122-step count are computed from the executed inference path before the gate can pass.

What runs

The vendored model is a 14,272-parameter, character-level transformer:

Property	Value
Transformer layers	1
Embedding width	32
Attention heads	4 × 8 dimensions
MLP width	128
Context length	8
Vocabulary	26 lowercase characters + BOS
Samples	20, using one deterministic global RNG stream

This artifact deliberately has a fixed model and configuration. It has no prompt interface and does not train; its achievement is the complete, bit-exact inference pipeline expressed in SQLite SQL.

How one SQL file does it

MGW binary
    → strict little-endian decode into relational weight tables
    → Q16.48 RMSNorm, Q/K/V projections, KV cache, causal attention, MLP
    → temperature, softmax, xorshift64 sampling
    → FNV-1a checksums over every raw logit word and generated byte

A table insert trigger supplies the sequencing that SQL does not normally have: 160 delivered ticks contain the 122 forward passes actually reached before BOS tokens end samples. Matrix products become joins plus integer SUM(), while scratch tables materialize recursive fixed-point results before reuse.

SQLite has signed 64-bit integers but no 128-bit type. The fixed-point layer therefore decomposes multiplication into limbs, implements division and transcendentals with recursive CTEs, reconstructs logical shifts explicitly, and spells XOR as (x | y) - (x & y). During development, the implementation was checked against the C oracle at all 69,748 recorded activation/logit/probability rows and all 122 RNG sampling records.

Verification

Run every non-mutating release gate:

make verify

Target	Purpose	Extra tools
make run	Run the standalone SQL artifact	sqlite3
make check	Diff stdout against the committed transcript	sqlite3, diff
make fp	Check 11,750 fixed-point vectors against the C oracle	Bash, Python 3, sqlite3
make model	Rebuild the F12 model and compare it byte-for-byte	Bash, Python 3.10+
make artifact	Prove microgpt.sql embeds all three SQL sources verbatim	Bash, awk, cmp
make golden-check	Rebuild and compare the three oracle fixtures	C11 compiler
make golden	Update vectors.txt, weights.txt, and trace.txt	C11 compiler

make golden is the only maintainer target above that rewrites tracked fixtures. reference/golden_transcript.txt is an inherited wide/packed/corrupt host fixture; the packed and deliberately corrupted input models are not vendored here, so that particular transcript is pinned rather than regenerated by this repository.

Repository map

Path	Purpose
microgpt.sql	Standalone SQL program; runs with the committed F12 model
sql/	Development fragments embedded verbatim in the artifact
model/	Wide source model, F12 model, and model card
reference/	Vendored C arithmetic/inference oracle and generated fixtures
tests/	Fixed-point and standalone-artifact gates
tools/	Reproducible F12 model conversion

SQLite landmines

• <<, >>, &, and | share one left-associative precedence level; every mixed shift/mask expression must be parenthesized.
• Recursive CTEs may reference themselves only directly in the recursive arm. Multi-step arithmetic is layered through scalar subqueries.
• Integer overflow in ordinary + and * silently promotes to REAL; limb arithmetic keeps every intermediate in range. SUM() is used as a loud overflow guard for accumulations.
• SQLite has no XOR operator, and arithmetic right shift must be masked to reconstruct a logical right shift.
• Positive decimal literals at or above 2^63 become lossy REAL; unsigned bit patterns must enter SQLite as signed int64 values.
• Trigger CTE syntax is restricted: the WITH clause belongs after the trigger's INSERT INTO destination.
• Recursive-CTE views recompute on every read, so expensive results are materialized before reuse.

Model trust and provenance

The runtime is designed for the committed, SHA-pinned model—not adversarial MGW input. The SQL loader validates the exact expected format, dimensions, and file size, but it expands bytes before completing every check; replacing the model with an untrusted huge file can exhaust resources. The FNV values are determinism regression checksums, not cryptographic integrity checks.

See the full model/README.md. The two model pins are:

466cfe9dba7b888cdaa23dedf4b10351826795793448c8e95dcb0f7a61ed33eb  model/model-wide.mgw
742cbd6d0b750bf3d164a23d97390171e3fe545ee9d87a2b0e843d3d8d1ae9f4  model/uniform-f12.mgw

Lineage:

1. Inspired by Andrej Karpathy's microgpt.
2. nmicic/int-llm independently rebuilds the character GPT in integer-only C and supplies the Q16.48 model/oracle.
3. nmicic/int-llm-precision-ladder produces the uniform-F12 weight artifact.
4. int-llm-sql expresses that exact inference computation relationally.

Created by Nenad Mićić as part of the int-llm family of reproducible integer inference experiments.

License

Apache-2.0 © 2026 Nenad Mićić. See LICENSE.