ActiveBlockference is a CPU-oriented Python library for discrete Active Inference experiments in radCAD and cadCAD. It provides deterministic grid worlds, multi-agent transitions, generative-model helpers, strict experiment configuration, persisted diagnostics, visualisation, and fail-closed validation.
This file is the GitHub-facing signpost. The source repository is the authoritative record; generated run outputs and notebook execution artefacts are intentionally not committed.
Choose the shortest path for your goal:
| Goal | Entry point |
|---|---|
| Install and run the library | README.md |
| Understand the public API | docs/api.md |
| Run a first experiment | docs/tutorials/01_single_agent.md |
| Configure a reproducible pipeline | docs/pipeline.md and configs/README.md |
| Understand the model and coordinates | docs/theory.md and docs/architecture.md |
| Read the generative-model specification | docs/gnn.md and specs/gridworld_3x3.gnn.md |
| Explore executable examples | notebooks/README.md |
| Read the publication source | docs/manuscript/README.md |
| Trace publication figures to their sources | docs/manuscript/figure-registry.json |
| Contribute or report a bug | docs/contributing.md |
| Report a security issue | SECURITY.md |
Requires Python 3.11 or newer and uv.
uv sync --locked --extra dev
uv run blockference pipeline \
--config configs/smoke.yml \
--output-root output \
--run-name first_run
uv run blockference validation --run-dir output/first_runThe pipeline writes a self-contained run directory containing configuration, trajectory and diagnostic tables, model and policy data, visualisations, logs, a manifest, and an aggregate validation report. Validation certifies software and artefact integrity; it does not establish that a scientific hypothesis is empirically adequate.
For a small Python API example, see the root README. For multi-agent runs,
provide distinct simulation.initial_states; the simultaneous-transition
environment rejects ambiguous starting positions.
GridWorldimplements bounded(y, x)coordinates, observations, simultaneous actions, collision resolution, and serialisation.ActiveGridferenceconstructs the discrete generative-model components and expected-free-energy policy machinery.ExperimentConfigloads strict YAML/TOML configuration and rejects unknown keys, invalid paths, malformed distributions, and invalid agent starts.run_pipelineruns seeded experiments, persists outputs atomically, renders diagnostics, and returns a singlePipelineResult.okrelease verdict.- The radCAD and cadCAD adapters share the same transition vocabulary, making backend comparisons about values rather than backend-specific formatting.
The core package is self-contained. Install the optional pymdp extra only
for the BlockferenceAgent adapter, and the research extra only for the
explicitly selected OpenAI GRTs provider. Offline tests and the release gate
do not require either extra.
The GitHub Actions workflow runs on pushes and pull requests targeting
main, using the committed uv.lock on Python 3.11 and 3.12. CI calls the
arms of the canonical gate in scripts/release_check.py:
- the
testmatrix contains only Python 3.11 and runs--arm test-full; - the Python 3.12
gnn-conformancejob (display namegnn conformance (pinned)) runs--arm allwithGNN_RUNTIME_PYTHONset to a separate pinned runtime provisioned fromspecs/gnn-pin.json. Independently reviewedGNN_BOOTSTRAPandGNN_SOURCE_MANIFESTinputs must also be delivered before hosted acceptance; source-only local proof does not establish installed provenance or provide those hosted artifacts.
The arms cover Ruff linting, repository-wide Markdown link/anchor validation,
mypy, the test suite, notebook hygiene and execution, real pipeline and CLI
smoke checks, manuscript validation/build drift, and a wheel import smoke.
The full test suite therefore runs on both Python versions without a separate
gate job. PDF rendering remains an explicit local --arm render selection.
docs/gate.md defines the arms, runtime-aware local
commands, and exact pinned astral-sh/setup-uv action; this workflow does not
use the Institute setup composite.
docs/_generated/gate-metrics.md holds
the measured numbers and the statuses of the one-run before/after receipts.
Those receipts are not a claimed speedup; the failed offline package baseline
cache miss remains a failure.
The no-argument fast default runs lint, types, the fast test selection, and
docs. The release gate's gnn arm always validates
specs/gridworld_3x3.gnn.md against the declared runtime model using the pinned
parser. The gate is intentionally fail-closed: a missing GNN runtime, required
backend, or generated artifact cannot turn a required check into a skip. See
docs/development.md for the development workflow
and docs/design-contract.md for the project
scope and invariants.
blockference/ installable library, CLI, environments, persistence, and viz
configs/ strict examples and smoke configuration
specs/ GNN model declaration and its pinned upstream parser record
docs/ concepts, API, tutorials, development, and manuscript source
notebooks/ executable teaching examples
GRTs/ optional provider-based local research workflow
tests/ unit, integration, artefact, publication, and notebook checks
scripts/ release, documentation, notebook, and manuscript validators
ActiveBlockference is a discrete, CPU-oriented research and teaching library. It is not a neural-network framework, a learned-embedding system, or a claim that a passing software validation report proves a model of the world. The formal assumptions, supported backends, determinism guarantees, and known limitations are documented in the design contract and manuscript.
The project is released under the MIT License. Contributions
should follow docs/contributing.md; security
reports should use the private GitHub advisory path described in
SECURITY.md.