fep_lean

fep_lean is a standalone catalogue of 50 Free Energy Principle, Active Inference, Bayesian Mechanics, Information Geometry, and Thermodynamics topics. Each row contains a natural-language statement, a Lean 4 theorem body, and typeset signatures. The pinned Lean workspace is the verification authority. The catalogue covers core formal results across five subdomains — 50 was the natural count after surveying the FEP literature; every topic has a maintained semantic review in config/theorem_maturity.yaml.

Contract

full execution is strict. It requires the pinned Lean/Lake/Mathlib workspace, the gauss executable, configured Hermes credentials, and writable SQLite state. Missing capability → complete: false, no report directory.

catalogue execution is deterministic and offline. It validates the complete YAML source and writes figures, manuscript variables, the unified appendix, and a report explicitly marked catalogue; it does not count topics as verified.

verify execution is Lean-only. Runs the native 50-topic compile sweep without Hermes or OpenGauss.

Releaseable for local verification. The full-mode credential-gated path (FEP-FULL-002 in TODO.md) is required before a publication claim can include live-LLM verification evidence. Until then, the local gates (tests, mypy, Lean, docs audits, report receipt validation) are the supported evidence boundary.

Quick start

uv sync --extra dev
uv run fep-lean catalogue
uv run fep-lean setup
uv run fep-lean verify
uv run fep-lean preflight
uv run fep-lean run

Use uv run fep-lean --help for filters, workflow selection, and project-root overrides. The equivalent maintained scripts are thin command wrappers in scripts/.

Source of truth

• config/topics.yaml is the validated 50-row catalogue.
• scripts/catalogue_sketches.py is the Lean body source; regenerate YAML with scripts/_maint_build_topics_catalogue.py.
• lean/FepSketches/fep_all.lean is the tracked aggregate generated by scripts/_maint_build_fep_all_lean.py.

Review contracts

• ISA.md defines the ideal state, anti-criteria, and evidence gates.
• TODO.md is the canonical open-only backlog with behavior-based acceptance probes.
• CHANGELOG.md records the local audit evidence and remaining release boundary.
• HANDOFF.md gives the next reviewer the operating protocol, evidence receipt, and remaining extension scope.

Development checks

uv run pytest tests/ -q --cov=src --cov-fail-under=89
uv run mypy src
uv run python docs/check_links.py --strict --include-root
uv run python docs/md_hygiene.py --strict
uv run python docs/pin_audit.py
uv run python docs/xref_audit.py

The reproducible build and publication gates are documented in docs/getting-started.md, docs/pipeline.md, and docs/cold-start-and-cleanup.md.

Layout

Path	Purpose
src/catalogue	strict YAML model and source parity checks
src/verification	read-only capability checks and Lean compiler bridge
src/llm	configured Hermes HTTP client
src/gauss	SQLite sessions and per-topic orchestration
src/output	figures, manuscript projections, and reports
src/pipeline	strict full and explicit offline catalogue modes
lean	pinned Lake workspace and tracked aggregate
manuscript	source chapters and generated publication inputs

Notation

A notation table mapping Lean identifiers in the catalogue to standard FEP notation (𝔽, 𝔖, 𝔈, KL-divergence, generalized coordinates) is maintained as part of the manuscript projections (manuscript/). The Lean code in lean/FepSketches/ uses descriptive identifiers (measure_union_le, elbo_bound, efe_monotone) to approximate standard conventions; the config/theorem_maturity.yaml assumption_review field bridges the FEP concept to the formal statement.