Epistemic Engine – verify AI-generated code and forecast what will break

Computational epistemology for software. It reads a codebase as a system of justified beliefs — claims the code makes about itself ("this function authenticates the caller", "this value is never null", "this uses approved crypto") — reconstructs how well-justified each one is from git history, and tracks how that confidence changes over time.

On top of that foundation it ships two tools you can use today:

— a pre-commit / CI verifier thatee guard

blocks unsafe or unjustified code before it lands(great for reviewing AI-generated changes).— forecastsee predict-chain

which beliefs are about to collapse, why, roughly when, and what it would cost to fix now vs. later — and it** tells you when it can't trust its own forecast.**

Everything is deterministic (no LLM, no network, no wall-clock in any computed value), runs offline, and is backed by 167 tests.

pip install epistemic-engine

Requires Python 3.10+. Apache-2.0 licensed.

ee ingest  ./my-repo        # read git history into a local graph
ee analyze ./my-repo        # extract beliefs, justifications, trajectories

ee guard   ./my-repo --all          # find unsafe / unjustified code
ee predict-chain ./my-repo          # forecast which beliefs will collapse
ee dashboard ./my-repo              # explore all of it in your browser

ee guard

extracts the beliefs a change makes about itself and blocks on risky ones, then layers on direct OWASP-class scanners and known-CVE matches. Each finding carries a severity, the reason, a concrete fix, and a stable fingerprint.

It catches, among others:

ee guard ./repo --staged          # verify staged changes (exit 1 = would block the commit)
ee guard ./repo --all             # verify the whole tree
ee guard ./repo --format sarif    # SARIF 2.1.0 for GitHub code scanning
ee guard ./repo --emit-workflow   # print a ready .github/workflows/ee-guard.yml
ee hook install ./repo            # run it automatically on every `git commit`

Adoption features so it fits a real team: inline # ee-ignore[rule]

suppression, a disabled_rules

config, and a baseline mode (--update-baseline

/ --baseline FILE

) that fails only on new findings so you can adopt on an existing repo without fixing everything first.

Field-tested on 1,500+ real production files: precision / recall / false-positive rate of 1.0 / 1.0 / 0.0 (95% CI lower bound 0.92 on a 114-sample corpus).

The engine already knows how each belief's confidence is eroding. predict-chain

projects that forward and, for each at-risk belief, gives you:

• a causal chain— the ranked factors driving the predicted collapse, each tagged** measured**(from your repo's history) or** assumption**(your cost model); - a collapse probability within a horizon, from a seeded Monte Carlo; - a calendar ETA from your repo's own commit cadence; - a fix + ROI, computed underyourcost assumptions and labelled as such.

ee predict-chain ./repo --horizon 30    # forecasts with causes, ETA, ROI
ee calibrate     ./repo                 # is the forecast trustworthy on THIS repo?

It refuses to lie. ee calibrate

runs a leakage-free back-test against your repo's own history and reports a Brier skill score vs. a base-rate baseline. If the model doesn't beat guessing on your repo, the report says so — and predict-chain

prints that verdict above every forecast. It never fabricates probabilities for undisclosed future CVEs, and never presents a dollar figure as fact.

ee dashboard ./repo      # loopback-only web UI; Ctrl-C to stop

A local, offline, self-contained dashboard with three tabs:

Beliefs— every claim the code makes, by domain, coloured by confidence.🔮 Predictions— the collapse forecasts, with the calibration verdict on top.🛡 Guard— theee guard

findings, grouped by severity, with a BLOCK/PASS banner. Scans the whole repo by default and caches the result.

Deterministic. Identical inputs produce byte-identical output. No LLM, no sampling, no wall-clock in any computed value — so results are reproducible and diffable in CI.Honest about uncertainty. Gates are evaluated on thelower boundof a Wilson confidence interval, not a point estimate. Predictions ship with a calibration verdict. Cost/ROI figures are labelled assumptions.Offline-first. No network access except an explicitee sync

.Bounded formalism. Beliefs outside the closed PO-1 predicate ontology are recorded asunformalised

and excluded from reasoning — never silently coerced.

pip install epistemic-engine                 # core (zero heavy dependencies)
pip install "epistemic-engine[parsing]"      # + tree-sitter for entity-level beliefs

Without the parsing

extra the engine degrades gracefully to file-granularity analysis. Python 3.10+.

Run ee <command> --help

for options, or ee man

for a full man page.

git clone <your-repo> && cd epistemic-engine
pip install -e ".[parsing,dev]"
pytest                       # 167 tests

Both are portability choices for a single-developer, offline-first, cross-platform (incl. Windows) build; neither changes observable semantics.

Graph store is abstracted behindstorage.GraphStore

with aSQLite default backend (zero-install, deterministic); RocksDB is optional.Git access goes through thegit CLI via subprocess, abstracted behindingestion.GitExtractor

.