Describe an Active Inference generative model once. Validate its structure, render framework-specific code, execute admitted models and inspect the evidence.
GNN is a human-readable, machine-parsable Markdown notation for Active Inference generative models. Use it to describe model assumptions in text, check their structure and run supported models through framework-specific implementations.
Quick start · Examples · Backends · Documentation · Release & paper · Roadmap · Contribute
Five conceptual stages in the 25-step workflow. Backend admission depends on the model contract; the illustration contains no measured results.
This repository provides the notation, curated model sources and a 25-step scientific workflow spanning parsing, validation, visualization, simulation, analysis and publication. Start with the CLI below, or explore the Python and service interfaces.
Software: 4.3.0. Published release records own accepted tags and assets.
FEP_Formal compatibility targets the fixed companion revision accepted with GNN 4.2.0. Full synchronization is planned for the next major release of both projects; see the baseline policy. Release notes describe the changes; package metadata owns version and dependency requirements. Page updated: 2026-10-21.
| Your goal | Best starting point |
|---|---|
| Run a first model | Quick start below, then the setup guide |
| Write or understand GNN | Language hub, syntax reference, examples tutorial |
| Choose a scientific example | Exemplar index and model-family manifest |
| Integrate a backend or interface | Backend guide, architecture, interface map |
| Inspect the release or paper | Release artifacts and citation |
| Contribute a focused improvement | TO-DO.md, CONTRIBUTING.md, AGENTS.md |
Install uv 0.13.4 and use Python 3.14 for the frozen default. Ordinary CI also tests Python 3.11–3.13. See the runtime exceptions and required profiles for the Python 3.15 HDF5 constraint, Python-specific scientific stack and the supported uv-only Gradio/Pillow override. Native GUI callbacks use Python 3.11–3.13.
git clone https://github.com/ActiveInferenceInstitute/Generalized_Notation_Notation.git
cd Generalized_Notation_Notation
git checkout v4.3.0
uv sync --frozen --python 3.14These commands select the released source. Contributors can use git switch main
before installing the development profile; the release tag
continues to identify the published artifacts.
uv run --frozen --no-sync gnn validate input/gnn_files/discrete/two_state_bistable.md --strict
uv run --frozen --no-sync gnn extract input/gnn_files/discrete/two_state_bistable.md --compactValidation reports 12 variables and 11 connections for this committed example. Extraction returns its two states, two observations, two actions and source-declared parameters as structured JSON.
uv run --frozen --no-sync gnn run \
--target-dir input/gnn_files/basics \
--output-dir output/quickstart \
--only-steps 3 5 6 7 8 \
--skip-steps 0 1 2This example parses, type-checks, validates, exports and visualizes the basic
models. --target-dir takes a directory; validate and extract take a
file. Pipeline prerequisites are resolved by the orchestrator. Each new run
gets its own identity; inspect its summary and artifacts under the selected
output directory.
What to inspect: validation diagnostics, exported model data and graph/matrix views. This selected workflow does not run native inference. To simulate a model, install its backend and follow that backend's admitted model examples below.
For simulation, use the full quick-start guide and backend setup. The full workflow can include native frameworks, Julia/Stan toolchains, GUI/audio and configured LLM providers; provision those dependencies and resource budgets for the steps you select. Configuration starts in input/config.yaml. LLM work reports coverage and context refusals; completion is accepted only for the source/prompt requests actually executed.
- Model assumptions you can read. Declare state spaces, connections, parameters, equations, time and ontology annotations for categorical POMDP and linear-Gaussian models.
- Checks before simulation. Validate dimensions, probabilities, covariance assumptions and scientific contracts, with explicit unsupported outcomes.
- Native backend workflows. Render code in Step 11 and supervise native scripts in Step 12 using the selected backend's packages and toolchain.
- Evidence tied to its source. Bind model identities, source hashes, configuration and artifact indexes to the current run. Required unfinished work prevents success. See the v4 run-ownership guide.
- Inspectable outputs. Produce graphs, matrix views, statistics, reports and static websites. Numerical comparisons require compatible model sources, inference semantics, inputs and precision.
- Several ways to work. Use CLI, Python, REST, MCP, editor/LSP or GUI; optional LLM, audio and ML integrations extend selected workflows. Durable runs support longer sessions.
The 4.3.0 numerical witness foundation independently reads a restricted source subset and compares finite path enumeration and joint-Gaussian conditioning with actual bnlearn/JAX filtering. It catches source, axis, action-time, horizon, covariance and precision mismatches within that explicit scope. It does not establish universal equivalence or a new Lean proof. See the minor changelog and E4 contract.
The 4.2.1 documentation update strengthens same-page/reference navigation checks, replaces unsupported configuration examples and scopes the next minor releases. See the patch changelog.
The 4.2.0 release updates RxInfer to 6.1.0 / ReactiveMP 7, refreshes compatible dependencies and security fixes, and adds a fast local release preflight and exact-source workflow collection. Independent Python tests and quality checks run concurrently; native, manuscript and paired acceptance retain their full scope. Read the release notes, migration guide and workflow guide.
A GNN model names its variables and dimensions, connects them and declares parameters separately. This excerpt comes from the complete two-state model:
## StateSpaceBlock
A[2,2,type=float] # Likelihood: observations × hidden states
s[2,1,type=float] # State belief
o[2,1,type=int] # Observation
## Connections
s-A
A-o
## InitialParameterization
A={
(0.8, 0.2),
(0.2, 0.8)
}The overview image and the diagram below are conceptual workflows; the architecture guide and module registry document the actual artifact dependencies and step prerequisites.
flowchart LR
S["GNN source + configuration"] --> I["Frozen selection + source identity"]
I --> V["Parse, type-check, validate"]
V --> R["11 · Render admitted code"]
R --> E["12 · Execute native scripts"]
E --> A["16 · Analyze compatible results"]
A --> P["Reports, website, run receipts"]
V --> D["Exports, graphs, ontology"]
Inputs live in input/gnn_files/. Generated artifacts live under the selected output directory; the repository's committed output/ contains publication evidence with its own recorded provenance. Consult the current run summary before treating an artifact as evidence for a new run.
| Model family or question | Example sources and guidance |
|---|---|
| Learn the notation | Static perception, dynamic perception |
| Minimal categorical agent | Two-state bistable POMDP, simple MDP |
| GridWorld and framework comparison | GridWorld folder |
| Linear-Gaussian dynamics and control | Continuous navigation, damped oscillator |
| Explicit independent Gaussian agents | Independent-agent exemplar; admitted native JAX/RxInfer contracts |
| Hierarchy and epistemic policies | Block-reset hierarchy, temporal controller, episodic T-maze; explicit JAX contracts |
| Learning, precision and multi-agent models | Full exemplar index, cognitive phenomena |
| Scaling studies | PyMDP scaling examples; compare matched run receipts |
An exemplar's declared contract determines backend admission. Composed, nonstationary and coupled models have specific supported/unsupported outcomes; the family manifest and scientific acceptance receipt record the selected cases and numerical evidence.
The renderer registry and executor specifications describe the maintained implementations. Generator availability, installed native dependencies, model admission and numerical acceptance are separate checks.
| Backend | Scope and setup reference |
|---|---|
| PyMDP | Categorical POMDP/MDP inference and action selection |
| JAX | Admitted categorical and linear-Gaussian models, plus explicitly declared scientific/composed contracts |
| RxInfer.jl | Julia message-passing implementations for admitted categorical and Gaussian contracts |
| ActiveInference.jl | Julia categorical Active Inference |
| PyTorch, NumPyro, Stan | Framework-specific categorical and linear-Gaussian render/execute paths; install the corresponding package/toolchain |
| DisCoPy, bnlearn | Categorical diagrams and Bayesian-network workflows under their adapter contracts |
| ngc-learn | Continuous linear-Gaussian/predictive-coding contract; see the adapter's model admission |
| cpomdp | Explicitly selected experimental released-wheel continuous backend, with bounded policy/resource options and numerical witnesses |
| THRML | Explicitly selected experimental finite categorical Gibbs smoothing under fixed actions, using released thrml==0.1.4 |
THRML admits strictly positive models; structural zeros, continuous models, cross-agent coupling and action optimization are outside its current contract. Native sample witnesses support the reported empirical marginals; convergence, exact inference and hardware execution require separate evidence.
See the implementation index for complete adapter documentation and setup guide for optional extras and Julia environments. CatColab is covered in the related modeling documentation.
Numbered scripts in src/gnn/ delegate to their module owners. Use selected steps for a focused task or the full pipeline for a provisioned workflow. The module documentation index and root AGENTS guide provide implementation details.
Expand the complete step map (0–24)
| Step | Module guide | Purpose |
|---|---|---|
| 0 | Template | Initialize the pipeline |
| 1 | Setup | Inspect/setup dependencies |
| 2 | Tests | Execute test selections |
| 3 | GNN | Discover and parse selected sources |
| 4 | Model registry | Model metadata and versioning |
| 5 | Type checker | Dimensions, types and resource estimates |
| 6 | Validation | Semantic and consistency checks |
| 7 | Export | Generate exchange formats |
| 8 | Visualization | Graph and matrix views |
| 9 | Advanced visualization | Additional plots and interactive artifacts |
| 10 | Ontology | Map model terms to ontology concepts |
| 11 | Render | Generate admitted backend code |
| 12 | Execute | Supervise native simulation scripts |
| 13 | LLM | Configured model interpretation and analysis |
| 14 | ML integration | Machine-learning integrations |
| 15 | Audio | Sonification and audio artifacts |
| 16 | Analysis | Statistics and source-compatible comparison |
| 17 | Integration | Coordinate cross-module outputs |
| 18 | Security | Security validation and access controls |
| 19 | Research | Research tooling and experimental features |
| 20 | Website | Publish static run views |
| 21 | MCP | Discover and expose model tools |
| 22 | GUI | Headless artifacts and interactive editors |
| 23 | Report | Assemble current-run reports |
| 24 | Intelligent analysis | Summarize the current run |
| Surface | Entry point and documentation |
|---|---|
| Python | Installed gnn.* package; API reference |
| CLI | gnn; commands and exit codes |
| REST | gnn serve; service guide |
| MCP | gnn mcp list / gnn mcp info; transport guide, tool reference |
| Editor/LSP | gnn lsp; LSP guide |
| GUI | gnn gui; GUI guide |
| Templates | gnn templates list / gnn pull; template documentation |
| Read next | What it covers |
|---|---|
| Guided start, learning paths | Onboarding for researchers and developers |
| GNN documentation hub, DOCS.md | Language, pipeline and integration maps |
| Syntax, schema, type system | Model authoring and interpretation |
| Architecture, SPEC.md | Implementation boundaries and declared behavior |
| Setup, operations, troubleshooting | Installation, commands and diagnosis |
| Active Inference, cognitive models | Scientific background and example domains |
| Testing guide, verification commands | Acceptance and reproducibility |
| Durable runs, orchestration contracts | Manifests, resumption and container plans |
| FEP/GEO paired revisions | Cross-repository custody and coordinated owner changes |
The published 4.2.0 record uses its version release for ordinary wheel/sdist, manuscript, source-bound verification records and checksums. Actual tag/source/check identities and directly downloaded asset hashes establish acceptance.
Read the 4.2.0 manuscript PDF and release overview. Main may contain later documentation changes; release artifacts retain their original source and tag identities. Historical releases and receipts remain linked from CHANGELOG.md.
For academic use, follow CITATION.cff. The initial publication is Smékal, J., & Friedman, D. A. (2023), Generalized Notation Notation for Active Inference Models, Active Inference Journal. The project concept DOI identifies the project. Exact-version source and distribution archival require separate acceptance; see the archive procedure and remaining archival work.
The repository is maintained by the Active Inference Institute community and licensed under CC BY-NC-SA 4.0.
The 4.3.0–4.9.0 delivery plan sets bounded scope, dependencies, review ownership and acceptance for each target.
The forward-only roadmap owns scope, priority, acceptance evidence and dependencies for remaining work. Browse minor work and major work, or choose a scoped open issue. Effort size and release version are separate decisions.
Start with CONTRIBUTING.md and the agent/contributor guide. Propose focused changes with a source baseline and acceptance evidence; use current CI for test outcomes and timings. The handoff checklist helps make completed work reviewable.
- Issues: reproducible bugs and scoped work.
- Discussions: modeling questions and ideas.
- SUPPORT.md: help and community channels.
- SECURITY.md: vulnerability reporting.
- CODE_OF_CONDUCT.md: participation standards.
- Contributors: contribution history.
| Path | Role |
|---|---|
| src/gnn/ | Installed Python package, numbered orchestrators and module implementations |
| input/ | Model sources, family manifest and configuration |
| output/ | Committed publication artifacts and recorded provenance |
| tests/ | Behavior, contract and integration checks |
| docs/ | Language, framework, scientific and operator guides |
| scripts/ | Audits, acceptance tools and publication tooling |
| pyproject.toml, uv.lock | Package metadata and locked dependencies |
| Root README | Extended project narrative and examples |
Maintainer reference: .github files, workflows and local checks
AGENTS.md defines folder guardrails; SPEC.md defines its purpose. workflows/README.md documents triggers and exact workflow commands, with workflow AGENTS and SPEC for maintainers. Dependabot configuration is in dependabot.yml; CodeQL configuration is in codeql/codeql-config.yml.
The overview PNG was generated with the built-in imagegen tool on 2026-10-21; its exact prompt is retained alongside it. The illustration explains the workflow and contains no measured results. Its numbered cards are presentation stages, not pipeline step numbers. The separately published 4.2.0 release overview retains its original release identity.
| Workflow or configuration | Purpose |
|---|---|
| comprehensive-native-coverage.yml | Separate exact-source Python 3.11/3.12/3.13 native coverage reports with original scope and floor, process provenance and exact line unions; procedure and limits |
| ci.yml | Python 3.11/3.12/3.13/3.14 tests; 3.12 lint/types/docs/capability checks; pipeline contracts; optional-dependency and Bandit lanes |
| installed-platforms.yml | Ordinary installed-wheel native acceptance outside the checkout: Linux 3.11/3.12/3.14, macOS 3.14 and Windows 3.14; acceptance scope and limits |
| local-gates.yml | Repository, manuscript-token and hydration gates |
| docs-audit.yml | Focused strict documentation and terminology audits |
| mcp-audit.yml | MCP inventory regression gate |
| codeql.yml | Python security analysis |
| dependency-review.yml | PR dependency/license review; fork limitations |
| supply-chain-audit.yml | Scheduled vulnerability checks on locked exports |
| full-extras.yml | Scheduled/manual all-extras installation and acceptance |
| rxinfer.yml | Native RxInfer 6.1 / ReactiveMP 7 tests on Julia 1.13.2, with environment-drift checks |
| gridworld.yml | GridWorld publication checks |
| actionlint.yml | Workflow YAML validation |
| fep-lean-paired-revision.yml, fep-lean-pair.json | Pinned FEP bridge custody checks |
| geo-infer-interchange.yml, gnn-pair.json | Pinned GEO interchange checks |
| pair-pin-freshness.yml | Scheduled companion-pin freshness checks |
| custody-re-render.yml | Scheduled/manual fresh manuscript-render audit |
CI runs on documentation PRs too. Documentation, paired-custody, security and repository gates provide complementary evidence. Exact selections, environment requirements, schedules and permission scopes live in the workflow files.
From a development checkout on main, install the locked development tools,
then run the documentation checks appropriate to this page. just release-preflight
provides the shared fast preflight before hosted release qualification:
uv sync --frozen --extra dev --python 3.14
uv run --frozen --no-sync python docs/development/docs_audit.py --strict --check-anchors --no-write
uv run --frozen --no-sync python scripts/check_doc_contracts.py --strict
uv run --frozen --no-sync python scripts/check_repo_terminology.py --strict
uv run --frozen --no-sync python scripts/check_maintained_doc_terms.py --strict
uv run --frozen --no-sync python scripts/check_gnn_doc_patterns.py --strict
uv run --frozen --no-sync python scripts/check_capability_contracts.py --strictFor source changes use the current verification commands
and the workflows' declared environments. Run actionlint .github/workflows/*.yml
when workflow YAML changes. Count-changing manuscript/source/test edits follow
the full rendering/custody procedure in AGENTS.md.