| title | Cognitive Active Inference |
|---|---|
| type | package |
| status | stable |
A Python package for Active Inference agents, and an Obsidian vault of linked pages that explain the mathematics, biology, cognitive science and philosophy behind it. The package is the executable reference; the vault is the explanation. Each side points at the other.
| I want to | Go to |
|---|---|
| Run an agent in five minutes | Quick start |
| Understand how an agent decides | How one step works |
| Learn the theory in order | Reading path |
| Find a concept page | knowledge_base/catalog.md |
| See what code exists | Package map and Agents |
| Reproduce the paper | Manuscript |
| Contribute | Contributing |
After provisioning the locked dependencies, the package, test suite, and
offline documentation gates do not need network access. Manuscript HTML needs
Pandoc and pandoc-crossref; PDF also needs XeLaTeX. The no-render pipeline
skips those renderers. The GNN conformance job needs the upstream parser pinned in
specs/gnn-pin.json, and the OKN replay job needs the
captured cross-graph evidence in docs/okn/evidence/. The hosted quality
workflow is optional. The core package, the
knowledge base and the documentation gate need no credentials and no private
checkout.
Python 3.11 or newer:
python -m pip install -e ".[dev]"Build a two-state model, infer beliefs after an observation, and infer a distribution over actions:
import numpy as np
from cognitive import ActiveInferenceDispatcher, DiscreteGenerativeModel, InferenceConfig, ModelState
model = DiscreteGenerativeModel(
A=np.array([[0.9, 0.1], [0.1, 0.9]]), # P(o | s)
B=np.stack([np.eye(2), np.array([[0.1, 0.9], [0.9, 0.1]])], axis=2), # P(s' | s, a)
C=np.array([0.0, 1.0]), # log-preference over o
D=np.array([0.5, 0.5]), # prior over s
E=np.array([0.5, 0.5]), # prior over a
)
dispatcher = ActiveInferenceDispatcher(
InferenceConfig(
method="variational",
policy_type="discrete",
temporal_horizon=2,
learning_rate=0.5,
precision_init=1.0,
seed=7,
),
model,
)
state = ModelState(model.D.copy(), model.E.copy(), 1.0, 0.0, 0.0)
beliefs = dispatcher.dispatch_belief_update(1, state) # q(s) after observing o = 1
policies = dispatcher.dispatch_policy_inference(state) # distribution over actions
assert np.isclose(beliefs.sum(), 1.0)
assert np.isclose(policies.sum(), 1.0)The editable install also provides these commands:
| Command | Purpose |
|---|---|
cognitive-benchmark |
Time the runtime components |
cognitive-build-manuscript |
Build the executable manuscript |
cognitive-validate-docs |
Run the documentation gate |
cognitive-verify-links |
Check [[wiki links]] |
cognitive-kb-index |
Check or regenerate the knowledge-base catalogs |
cognitive-export-rdf |
Export the knowledge base as RDF for the Open Knowledge Network |
cognitive-normalize-frontmatter |
Check or fix semantic_relations frontmatter |
cognitive-create-node |
Create a knowledge-base page from a template |
An agent holds beliefs q(s) about hidden states. Each step it updates them from
what it observed, scores every candidate policy by expected free energy G, and
turns those scores into a distribution over actions.
flowchart LR
O["observation o"] --> BU["dispatch_belief_update"]
Q0["beliefs q(s)"] --> BU
BU --> Q1["posterior q(s)"]
Q1 --> EFE["expected free energy G per policy"]
GM["generative model A, B, C, D, E"] --> BU
GM --> EFE
EFE --> SM["softmax of -G / temperature, times prior E"]
SM --> PI["distribution over actions"]
PI --> ACT["action a"]
ACT -. "next step" .-> O
The generative model is five arrays, validated on construction:
| Array | Meaning | Theory page |
|---|---|---|
A[o, s] |
likelihood P(o | s) |
generative models |
B[s', s, a] |
transitions P(s' | s, a) |
POMDP structure |
C[o] |
log-preferences over observations | expected free energy |
D[s] |
prior over initial states | belief updating |
E[a] |
prior over actions | policy selection |
The dispatcher offers three inference methods and discrete policy sequences with explicit horizons, temperatures and seeds. All of its methods return finite, normalized distributions.
flowchart TB
CFG["InferenceConfig"] --> D["ActiveInferenceDispatcher"]
D --> V["variational"]
D --> M["mean_field"]
D --> S["sampling"]
V --> OUT["normalized beliefs and policies"]
M --> OUT
S --> OUT
Method background: variational inference, variational free energy, message passing, precision.
expected_free_energy returns the canonical objective and its parts:
G = D_KL(q(o) || p*(o)) + E_q(s)[H(P(o | s))]
\_____ risk _____/ \____ ambiguity ____/
Ambiguity equals H[q(o)] - I(s; o), so the expected information gain is already
inside it. The package returns the gain as a fourth value for inspection and does
not subtract it from the total a second time. InferenceConfig.exploration_weight
adds an explicit information-seeking bias; it defaults to 0.0.
Derivation and intuition:
expected free energy,
in the free energy principle,
information gain,
KL divergence.
flowchart TB
subgraph pkg ["cognitive (code/tools/src)"]
MODELS["models/active_inference<br/>dispatcher, generative model,<br/>base model, homeostatic control"]
MATS["models/matrices<br/>MatrixOps, MatrixLoader"]
UTILS["utils<br/>matrix_utils, create_node,<br/>network visualization"]
VIZ["visualization<br/>MatrixPlotter, StateSpacePlotter"]
BENCH["benchmarks"]
end
subgraph things ["Things (code/Things)"]
SP["Simple_POMDP"]
CG["Continuous_Generic"]
end
subgraph scripts ["scripts (code/scripts)"]
GATES["validate_docs, verify_links,<br/>check_markdown_links,<br/>kb_index, export_rdf,<br/>normalize_frontmatter"]
MS["build_manuscript"]
MUT["mutation_check"]
end
MODELS --> MATS
MODELS --> UTILS
SP --> UTILS
CG --> UTILS
VIZ --> UTILS
GATES --> KB[("knowledge_base/")]
MS --> MAN[("docs/manuscript/")]
| Component | Read |
|---|---|
cognitive package |
code/tools/src/README.md, docs/api/README.md |
| Dispatcher and models | code/tools/src/models/active_inference/README.md |
| Tests | code/tests/README.md, docs/tools/mutation_testing.md |
| Configuration | config.yaml, docs/config/README.md |
| Every folder | project_structure.md |
code/Things/ is installed as the Things package. Two
of its folders contain code; the others are design notes with no importable
Python.
| Agent | Kind | What it is |
|---|---|---|
Simple_POMDP |
code | Discrete POMDP agent configured from a YAML path or dict; seeded, validated, with persistence, histories and expected-free-energy components |
Continuous_Generic |
code | Precision-weighted generalized-coordinate updates; multi-frame GIF animation through ContinuousVisualizer |
Generic_POMDP |
design notes | Matrix-configured discrete agent design |
Generic_Thing |
design notes | The abstract definition of an agent |
Ant_Colony |
design notes | Stigmergic foraging concept |
BioFirm, KG_Multi_Agent, Path_Network |
design notes | A firm as an agent; agents on a knowledge graph; agents on a dynamic network |
Theory behind them: POMDP framework, generalized coordinates, continuous-time models, Markov blankets, swarm intelligence, ant colony organization.
Start at knowledge_base/catalog.md. It lists every
domain, and each domain's catalog.md lists every page with its opening line.
The catalogs are generated by kb_index.py; do not edit them. The
glossary defines the vocabulary, and
linking standards say how pages connect. The pages
and their links are also published as an RDF graph (SKOS, Dublin Core, schema.org and PROV)
for the Open Knowledge Network; see docs/okn.
The RDF entity model distinguishes Markdown documents
from the concepts they describe. Document metadata and citations stay on page
resources; concept relationships and reviewed mappings use separate topic resources.
The keyword review records reuse of
established subject terms and the tags retained locally because their scope is uncertain.
The endpoint curation workflow groups ambiguous
source assertions for review. Join support makes local
mapping reviews and captured remote assertion origins inspectable offline.
flowchart TB
FEP["free_energy_principle<br/>the unifying principle"]
MATH["mathematics<br/>probability, information theory,<br/>inference, control"]
COG["cognitive<br/>perception, action, memory,<br/>decision making, social cognition"]
BIO["biology<br/>ecology, evolution,<br/>collective behaviour"]
SYS["systems<br/>complexity, emergence,<br/>self-organization"]
PHIL["philosophy<br/>epistemology, enactivism,<br/>mind"]
AG["agents<br/>architectures and designs"]
ONT["ontology<br/>shared vocabulary"]
RES["research<br/>directions and applications"]
CIT["citations<br/>references"]
BF["BioFirm<br/>biological firm theory"]
FEP --> MATH
FEP --> COG
FEP --> BIO
MATH --> AG
COG --> AG
BIO --> SYS
SYS --> COG
PHIL --> FEP
ONT -.-> MATH
ONT -.-> COG
RES -.-> AG
CIT -.-> FEP
BF --> BIO
| Domain | Scope | Enter at |
|---|---|---|
free_energy_principle |
The principle, its mathematics, applications across biology, cognition and systems | README, catalog |
mathematics |
Probability, information theory, variational inference, POMDPs, control | README, catalog |
cognitive |
Perception, attention, memory, decision making, social and collective cognition | README, catalog |
biology |
Ecology, evolution, colony organization, communication | README, catalog |
systems |
Complexity, emergence, self-organization, networks | README, catalog |
philosophy |
Epistemology, enactivism, philosophy of mind and science | README, catalog |
agents |
Agent architectures and the POMDP framework | README, catalog |
ontology |
Cross-domain vocabulary | README, catalog |
research |
Research directions and implementation notes | README, catalog |
citations |
Reference lists and sources | README, catalog |
BioFirm |
Biological firm theory in Active Inference terms | README, catalog |
The vault explains concepts; executable behavior is defined by the package and its tests. Pages may use pseudocode to illustrate an idea, and that code is not package API.
flowchart LR
A["Bayes' theorem"] --> B["Variational inference"]
B --> C["Variational free energy"]
C --> D["Free energy principle"]
D --> E["Generative models"]
E --> F["Expected free energy"]
F --> G["Policy selection"]
G --> H["Active inference as a POMDP"]
H --> I["Run it: Quick start"]
- Bayes' theorem
- Variational inference
- Variational free energy
- Free energy principle
- Generative models
- Expected free energy
- Policy selection
- Active inference as a POMDP
Longer routes by background: learning roadmap, guides and learning paths. From the cognitive side: active inference, predictive coding, the Bayesian brain, hierarchical models.
docs/README.md is the curated documentation hub for the
implemented package and the process around it. The separate generated
docs/documentation-index.md lists long-lived
Markdown recursively, including the manuscript and tools sub-trees, while
excluding agent instructions and the index itself.
| Folder | Contents |
|---|---|
docs/api/ |
Exports, signatures, executed examples, version policy |
docs/guides/ |
Application notes and learning paths |
docs/cli/ |
The cognitive command: settings, simulate, sweep, benchmark |
docs/visualization/ |
Figure gallery for simulations and the knowledge base |
docs/architecture/ |
How settings, simulation, plots and the command fit together |
docs/config/settings.md |
Every setting, its default and its layering |
examples/ |
Discrete, continuous and hierarchical episodes, sweeps and graph reports |
docs/examples/ |
Example pages |
docs/tools/ |
One page per shipped tool or gate |
docs/development/ |
Development loop and contribution rules |
docs/repo_docs/ |
Setup, documentation standards, linking, naming, testing |
docs/implementation/rxinfer/ |
Notes on RxInfer.jl, an external project |
docs/policy/ |
The term policy the documentation gate enforces |
docs/manuscript/ is a complete executable paper.
Every number and figure is generated from the package, so the text cannot drift
from the code.
flowchart LR
CFG["config.yaml"] --> B["cognitive-build-manuscript"]
SRC["numbered sections<br/>references.bib"] --> B
PKG["cognitive and Things APIs"] --> B
B --> FIG["figures and<br/>manuscript_variables.json"]
FIG --> MD["combined.md"]
MD --> H["manuscript.html"]
MD --> P["manuscript.pdf"]
B --> MAN["build_manifest.json"]
./run.sh manuscript # no-render checks, then HTML
./run.sh manuscript --pdf # also render PDF (requires XeLaTeX)Use the shared root entry point; bare ./run.sh defaults to test:
./run.sh lint # Ruff lint + format check + compileall
./run.sh types # mypy
./run.sh test # selected core-model tests only; no coverage
./run.sh test-full # entire suite with branch coverage
./run.sh docs # docs, index/evidence freshness, OKN checks
./run.sh gnn # validator + conformance; requires pinned runtime
./run.sh manuscript # no-render pipeline + HTML; --pdf adds PDFThe entry point invokes
uv run --locked --extra dev --python 3.12 python code/scripts/gate.py ARM
using uv.lock. GNN needs GNN_RUNTIME_PYTHON pointing to the independently
provisioned pinned parser; ./run.sh gnn --provision explicitly enables its
network provisioning. See development resources
for prerequisites and additional benchmark and mutation commands.
test-full measures branch coverage across the configured source tree, not a
chosen subset (why). The docs arm includes
frontmatter, links, Python fences, catalogs, public exports, term policy,
manuscript references, documentation-index and gate-evidence freshness, and OKN
submission, quality, and semantic-review checks.
CI (quality.yml, described in
CI tools) is manually dispatched. Its
Hosted quality (optional) job runs core gates, manuscript HTML, benchmarks,
captured OKN replay, mutation qualification,
and package checks. The independent gnn-conformance job keeps its display name
gnn conformance (pinned) and separate parser interpreter. Both use
ActiveInferenceInstitute/.github/.github/actions/setup-python-uv@7159e67315330aac8e414aebae0ad1e999a41448
and the lockfile. The required tests status comes from the
local merge gate.
Tests write artifacts to temporary directories. Local measurement provenance
and results belong in the generated
gate measurements, sourced from
gate-measurements.json, rather than
copied counts or timings in guides. The term policy is in
docs/policy/documentation_terms.yaml.
- Read
AGENTS.mdanddocs/development/contribution_guide.md. - New pages follow
knowledge_base/linking_standards.md: YAML frontmatter with quotedsemantic_relationslinks, and[[wiki links]]only to pages that exist. - After adding or renaming a documentation page, regenerate the flat index with
uv run --locked --extra dev --python 3.12 python code/scripts/docs_index.py --write .. For knowledge-base pages, regeneratekb_index.py --write .in the same locked environment. Then run./run.sh docs. - Release notes are in
CHANGELOG.md; open work is tracked in the backlog file at the repository root.
Code is MIT (LICENSE). Repository-owned knowledge-base content and
RDF graph exports are CC BY 4.0,
under LICENSE-KNOWLEDGE-BASE.md.
Documentation outside the knowledge base remains CC BY-NC-SA 4.0.
This repository carries a committed .aii/ sidecar with curated
InstituteOS metadata (aii-sidecar/v1): category, maturity, ecosystem relations,
key artifacts, provenance, and portable tasks. It is read by
InstituteOS tooling and
does not affect the project's build or runtime.