Applied Epistemic Engineering for Python

An evidence-centered Python toolkit for turning important claims into inspectable engineering artifacts. It makes boundaries, evidence, provenance, uncertainty, contradictions, falsification tests, recovery work, and decision history explicit.

This is an original, ground-up ElectroHire implementation. Its result model aligns directly with ElectroHire's Spec Kit Evaluator Contract while the domain engine remains independently packaged.

Why it exists

Ordinary validation asks whether an artifact is formatted correctly. AEE asks harder questions:

• What exactly is being claimed?
• Under what conditions does it hold?
• What was observed, inferred, or merely asserted?
• What evidence would prove the claim wrong?
• Which claims depend on uncertain foundations?
• What contradicts the current conclusion?
• What bounded work would improve the decision?

The library does not call a confidence number “truth.” Every score is a transparent decision aid derived from recorded evidence and explicit rules.

Installation

pip install applied-epistemic-engineering

Requires Python 3.11 or later; tested on Linux, macOS, and Windows with Python 3.11, 3.12, and 3.13.

Using Spec Kit? You don't need to install this package yourself. Install the Spec Kit extension, which installs a compatible engine (applied-epistemic-engineering>=1.5.0,<2, the latest available) and its other dependencies automatically on first use:

specify extension add aee --from https://github.com/electrohire/spec-kit-aee/archive/refs/tags/v1.5.1.zip

The example pins spec-kit-aee 1.5.1, the extension release tested with this engine; check its releases for newer versions. spec-kit-aee is a Spec Kit extension distributed as a GitHub release archive, not a PyPI package, and is versioned independently of this engine.

For development:

pip install -e ".[dev,docs]"

Five-minute example

from aee import (
    AEESession,
    ClaimKind,
    ClaimStatus,
    Evidence,
    EvidenceKind,
    SourceQuality,
)

session = AEESession(
    "checkout-service",
    phase="after_plan",
    ledger_file=".aee/epistemic-ledger.jsonl",
)

claim = session.add_claim(
    "REQ-PERF-001",
    "Checkout p95 latency remains below 300 ms",
    kind=ClaimKind.REQUIREMENT,
    boundary=["production", "nominal load", "30-minute observation window"],
    source_ref="spec.md#REQ-PERF-001",
)
claim.status = ClaimStatus.SUPPORTED
claim.falsification_tests.append("Observe p95 latency at or above 300 ms")

session.add_evidence(
    claim.id,
    Evidence(
        ref="reports/load-test-2026-09-04.json",
        kind=EvidenceKind.OBSERVED,
        source_quality=SourceQuality.TEST,
        source_id="load-test-2026-09-04",
        description="Observed p95 latency was 241 ms",
    ),
)

assessment = session.assess()
print(assessment.outcome, assessment.summary)

CLI

aee assess --input claims.json --phase after_plan --output assessment.json \
  --evaluator-output evaluator-result.json
# assess ledgers by default (Spec 002 FR-8.1): the assessment above was
# also appended to .specify/extensions/aee/ledger/epistemic-ledger.jsonl
# under the project root (the CWD, or --project-root when given) — the
# same default the spec-kit-aee runner uses. --ledger <path> selects a
# different ledger; --no-ledger opts out, and the choice is echoed into
# the assessment metadata either way.
aee verify-ledger --ledger .specify/extensions/aee/ledger/epistemic-ledger.jsonl

aee challenge --input claims.json --phase after_plan --output challenge.json
aee validate claims.json   # strict load + structural checks (CI: 0 valid, 2 invalid)
aee verify-evidence claims.json --project-root .   # refs resolve, hashes recompute, quality is derived vs declared
aee assess --input claims.json --verify-evidence --project-root .   # the same checks, folded into the assessment
aee gaps --matrix specs/verification-matrix.md --evidence evidence/ --output GAPS.md
aee graph --input claims.json --output claim-graph.mmd
aee gate --input assessment.json
aee demo   # self-contained demonstration assessment

# With the epistemic-ledger policy gates and measured source reliability:
aee assess --input claims.json --policy --reliability reliability.json
# Diff two assessments into a materiality-filtered review queue:
aee review --previous assessment-t1.json --current assessment-t2.json

Exit codes are CI-friendly: 0 for pass/warn, 1 for iteration/clarification/evidence collection/abstention, and 2 for a hard block or invalid ledger.

The ledger is the record; the JSON is a working copy (Spec 002 FR-8.3). Each ledger entry stores the assessment's SHA-256 alongside its project, phase, outcome, and claim ids, so the entry — not the assessment file, which tools routinely overwrite on the next run — is the durable record of what was assessed. The documented loop is aee assess → aee verify-ledger --ledger <path>; the CLI and the spec-kit-aee runner describe identical semantics (ledger by default, same default path, --no-ledger as the explicit opt-out).

Architecture

Core principles

1. Assertions never become observations because a model repeats them.
2. Counterevidence and contradictions remain visible.
3. Unsupported claims remain explicitly unsupported.
4. Confidence propagates through dependencies by the weakest-link rule.
5. Every failure produces a bounded recovery proposal with a verification condition.
6. Deterministic checks run before probabilistic review.
7. Hash chains establish tamper evidence—not truth, identity, or trusted time.

Documentation

Full documentation is published on Read the Docs at applied-epistemic-engineering.readthedocs.io. Users adopting AEE from another implementation can follow the migration guide. How the engine, extension, and catalog versions relate is specified in the version policy.

Ownership and license

Designed and implemented by ElectroHire Inc. Copyright © 2026 ElectroHire Inc. Released under the MIT License.