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

> Source: <https://github.com/aswinsasi/epistemic_engine>
> Published: 2026-07-25 11:36:02+00:00

**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 that`ee guard`

**blocks unsafe or unjustified code before it lands**(great for reviewing AI-generated changes).— forecasts`ee 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:

| Class | Examples |
|---|---|
| Weak crypto | `md5` /`sha1` /`mt_rand` used as a security primitive |
| Injection | SQL built by string concatenation, `os.system` /`popen` on user input |
| Unsafe sinks | `eval` , `innerHTML` , `unserialize` , `pickle.loads` on untrusted data |
| Secrets | hardcoded API keys / tokens (the value is never printed or stored) |
| Misconfig | TLS verification off, `Access-Control-Allow-Origin: *` , debug enabled |

```
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 under*your*cost 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**— the`ee 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 the*lower bound*of 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 explicit`ee sync`

.**Bounded formalism.** Beliefs outside the closed PO-1 predicate ontology are recorded as`unformalised`

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+.

| Command | What it does |
|---|---|
`ee ingest <repo>` |
Read git history into the local epistemic graph |
`ee analyze <repo>` |
Extract beliefs, justifications, change events, trajectories |
`ee guard <repo>` |
Verify changed/all code; block unsafe or unjustified beliefs |
`ee hook install <repo>` |
Install a git pre-commit hook running `ee guard --staged` |
`ee predict-chain <repo>` |
Forecast belief collapse with causes, ETA, and ROI |
`ee calibrate <repo>` |
Back-test the forecast model against the repo's own history |
`ee dashboard <repo>` |
Serve the local web dashboard |
`ee report <repo>` |
Epistemic health report (text / json / markdown / html) |
`ee beliefs / falsifiers / debt / timeline` |
Inspect specific slices |
`ee doctor` |
Validate environment, ontology, and configuration |

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 behind`storage.GraphStore`

with a**SQLite** default backend (zero-install, deterministic); RocksDB is optional.**Git access** goes through the**git CLI** via subprocess, abstracted behind`ingestion.GitExtractor`

.