Skip to content
ActiveInferenceInstitutePublic

About

Knowledge base and Python package for discrete and continuous Active Inference: generative models, expected free energy, POMDP simulation, and an executable manuscript with reproducible validation commands.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

23 stars

Watchers

3 watching

Forks

title Cognitive Active Inference
type package
status stable

Cognitive Active Inference

quality

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

Status

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.

Quick start

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

How one step works

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
Loading

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
Loading

Method background: variational inference, variational free energy, message passing, precision.

Expected free energy

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.

Package map

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/")]
Loading
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

Agents

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.

The knowledge base

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

Reading path through the theory

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"]
Loading
  1. Bayes' theorem
  2. Variational inference
  3. Variational free energy
  4. Free energy principle
  5. Generative models
  6. Expected free energy
  7. Policy selection
  8. 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.

Documentation

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

Manuscript

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"]
Loading
./run.sh manuscript        # no-render checks, then HTML
./run.sh manuscript --pdf  # also render PDF (requires XeLaTeX)

Quality gates

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 PDF

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

Contributing

  • Read AGENTS.md and docs/development/contribution_guide.md.
  • New pages follow knowledge_base/linking_standards.md: YAML frontmatter with quoted semantic_relations links, 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, regenerate kb_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.

License

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.

InstituteOS sidecar

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.

About

Knowledge base and Python package for discrete and continuous Active Inference: generative models, expected free energy, POMDP simulation, and an executable manuscript with reproducible validation commands.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

23 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages