Generalized Notation Notation (GNN)

Describe an Active Inference generative model once. Validate its structure, render framework-specific code, execute admitted models and inspect the evidence.

The GNN 4.0.0 release artwork illustrates the current-run contracts carried forward in the latest maintenance release, 4.0.1.

Quick start · Examples · Backends · Documentation · Release & paper · Roadmap · Contribute

GNN is a human-readable, machine-parsable Markdown notation for Active Inference generative models. This repository provides the notation, curated model sources and a 25-step scientific workflow spanning parsing, validation, visualization, simulation, analysis and publication. Researchers can inspect model assumptions in text; developers can use the installed gnn Python package, CLI and service interfaces.

Current release: GNN 4.0.1. Page updated: 2026-10-07. Package metadata is canonical in pyproject.toml; release history is in CHANGELOG.md.

What GNN 4 delivers

• Readable model specifications. Declare state spaces, connections, parameters, equations, time and ontology annotations. Maintain categorical POMDP and linear-Gaussian models with explicit model-kind admission.
• Validation before simulation. Check shapes, probabilities, covariance assumptions and declared scientific contracts; retain actionable failure and unsupported outcomes.
• Framework-specific rendering and execution. Step 11 generates code; Step 12 supervises native scripts. Optional packages and toolchains are installed for the selected backend and model contract.
• Evidence tied to one invocation. Frozen selection, path-derived model identities, source hashes, resolved configuration, artifact indexes, output leases and a shared deadline bind the current run. Required unfinished work prevents success. Read the v4 migration guide.
• Scientific analysis and communication. Produce graphs, matrix views, statistics, reports and static websites. Numerical comparisons require compatible source identities, inference semantics, inputs and precision; Gaussian uncertainty is derived from covariance.
• Interfaces for people and tools. Use CLI, REST, MCP, editor/LSP and GUI surfaces, with optional LLM analysis, audio and ML integrations. Durable run manifests, resumable acceptance sessions and auditable container plans support longer workflows.

The 4.0.1 maintenance patch improves GUI parsing complexity, locked dependency security, complete subprocess input delivery and LLM coverage diagnostics. Its publication receipt records accepted source/tag identities, companion checks and verified release artifacts. Full-source long-context LLM completion and broader scientific semantics remain scoped in the forward roadmap.

Start here

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

Quick start

Install uv and use Python 3.12 for this example. CI also runs Python 3.11 and 3.13; additional platform/runtime acceptance is tracked in TO-DO.md.

Install the released source

git clone --branch v4.0.1 --depth 1 https://github.com/ActiveInferenceInstitute/Generalized_Notation_Notation.git
cd Generalized_Notation_Notation
uv sync --frozen --python 3.12

Inspect one model

uv run --frozen gnn validate input/gnn_files/discrete/two_state_bistable.md --strict
uv run --frozen gnn extract input/gnn_files/discrete/two_state_bistable.md --compact

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

Run a small local workflow

uv run --frozen gnn run \
  --target-dir input/gnn_files/basics \
  --output-dir output/quickstart \
  --only-steps 3 5 6 7 8 \
  --skip-steps 0 1 2

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

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.

From model source to evidence

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 diagram is a conceptual workflow; 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"]

Loading

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.

Choose a model

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.

Render and execute backends

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.

Pipeline: all 25 steps

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

Interfaces

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

Documentation map

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

Release artifacts and citation

The 4.0.1 release contains the wheel, source distribution, manuscript, source-binding and verification receipts, plus SHA256SUMS. Read the published manuscript PDF and publication receipt for the accepted release epoch. Main may contain subsequent documentation work; release artifacts retain their original source and tag identities.

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 and historical archive are distinct from a version-specific archive. Exact-version archival work is tracked under E5 in TO-DO.md.

The repository is maintained by the Active Inference Institute community and licensed under CC BY-NC-SA 4.0.

Next steps

The forward-only roadmap defines scope, priority, acceptance evidence and dependencies for each remaining workstream. Effort size and release version are separate decisions.

Effort	Upcoming scope
Minor	Documentation, diagnostics/dependency ratchets, released THRML fix verification, scientific presentation and archival publication
Medium	Module ownership, execution/interface contracts, filesystem/platform boundaries, meaningful coverage, measured performance and installed-package acceptance
Major	Full-source long-context LLM processing, coupled continuous agents, THRML/cpomdp extensions and formal-to-numerical semantics

Contributing and support

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.

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

Repository and automation guide

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

Automation in this folder

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.

Workflow index

Workflow or configuration	Purpose
ci.yml	Python 3.11/3.12/3.13 tests; 3.12 lint/types/docs/capability checks; pipeline contracts; optional-dependency and Bandit lanes
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
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.

Local validation

From a development checkout on main, install the locked development tools, then run the documentation checks appropriate to this page:

uv sync --frozen --extra dev --python 3.12
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 --strict

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