Skip to content

About

CPU-oriented Python library for discrete Active Inference experiments in radCAD and cadCAD: deterministic grid worlds, multi-agent transitions, generative-model helpers, and fail-closed validation.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

32 stars

Watchers

10 watching

Forks

Repository files navigation

ActiveBlockference

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.

CI License: MIT

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.

Start here

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

Quick start

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_run

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

What the package provides

  • GridWorld implements bounded (y, x) coordinates, observations, simultaneous actions, collision resolution, and serialisation.
  • ActiveGridference constructs the discrete generative-model components and expected-free-energy policy machinery.
  • ExperimentConfig loads strict YAML/TOML configuration and rejects unknown keys, invalid paths, malformed distributions, and invalid agent starts.
  • run_pipeline runs seeded experiments, persists outputs atomically, renders diagnostics, and returns a single PipelineResult.ok release 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.

Verification and CI

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 test matrix contains only Python 3.11 and runs --arm test-full;
  • the Python 3.12 gnn-conformance job (display name gnn conformance (pinned)) runs --arm all with GNN_RUNTIME_PYTHON set to a separate pinned runtime provisioned from specs/gnn-pin.json. Independently reviewed GNN_BOOTSTRAP and GNN_SOURCE_MANIFEST inputs 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.

Repository map

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

Scope and limitations

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.

About

CPU-oriented Python library for discrete Active Inference experiments in radCAD and cadCAD: deterministic grid worlds, multi-agent transitions, generative-model helpers, and fail-closed validation.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

32 stars

Watchers

10 watching

Forks

Releases

Packages

Used by

Contributors

Languages