GNN Tools and Resources

Version: v1.6.0 Engine (Bundle v2.0.0)
Last Updated: 2026-04-15
Status: Maintained

This document provides information about tools, libraries, and resources for working with Generalized Notation Notation (GNN).

GNN Tool Ecosystem

The GNN ecosystem includes various tools for different aspects of working with GNN files:

graph TD
    GNN[GNN Files] --> PARSER[Parsing Tools]
    GNN --> VIZ[Visualization Tools]
    GNN --> CONVERT[Conversion Tools]
    GNN --> VALID[Validation Tools]
    GNN --> EDIT[Editing Tools]
    
    PARSER --> PYPARSER[Python Parser]
    PARSER --> JSPARSER[JavaScript Parser]
    
    VIZ --> GRAPHVIZ[Static Visualizer]
    VIZ --> INTERACT[Interactive Visualizer]
    
    CONVERT --> PYCODE[Python Code Generator]
    CONVERT --> JULIACODE[Julia Code Generator]
    CONVERT --> LATEXGEN[LaTeX Generator]
    
    VALID --> SYNTAX[Syntax Checker]
    VALID --> SEMANT[Semantic Validator]
    
    EDIT --> IDE[IDE Plugins]
    EDIT --> WEBAPP[Web Editor]
    
    classDef core fill:#f96,stroke:#333,stroke-width:2px;
    classDef category fill:#9cf,stroke:#333,stroke-width:1px;
    classDef tool fill:#cfc,stroke:#333,stroke-width:1px;
    
    class GNN core;
    class PARSER,VIZ,CONVERT,VALID,EDIT category;
    class PYPARSER,JSPARSER,GRAPHVIZ,INTERACT,PYCODE,JULIACODE,LATEXGEN,SYNTAX,SEMANT,IDE,WEBAPP tool;

Parsing Tools

GNN Parser (Repository CLI)

The repository provides parsing through the gnn CLI and Step 3 orchestrator:

# Parse files with the CLI
uv run gnn parse --target-dir input/gnn_files --output-dir output

# Parse via step-3 script
uv run python src/3_gnn.py --target-dir input/gnn_files --output-dir output --verbose

GNN Parser API Reference

Command	Description	Output
`uv run gnn parse --target-dir <dir> --output-dir <dir>`	Parse and serialize GNN models	`output/3_gnn_output/`
`uv run gnn validate --target-dir <dir>`	Validate GNN syntax and structure	validation report + exit status
`uv run python src/main.py --only-steps "3,5"`	Parse then type-check	`output/3_gnn_output/`, `output/5_type_checker_output/`

Visualization Tools

GNN Graph Visualizer

The GNN Graph Visualizer creates graphical representations of GNN models:

graph TD
    subgraph Visualization Process
        GNN[GNN File] --> PARSE[Parse Model]
        PARSE --> LAYOUT[Compute Layout]
        LAYOUT --> RENDER[Render Graph]
        RENDER --> OUTPUT[Generate Output]
    end
    
    subgraph Output Formats
        OUTPUT --> SVG[SVG]
        OUTPUT --> PNG[PNG]
        OUTPUT --> HTML[Interactive HTML]
        OUTPUT --> PDF[PDF]
    end
    
    classDef process fill:#9cf,stroke:#333,stroke-width:1px;
    classDef format fill:#cfc,stroke:#333,stroke-width:1px;
    
    class GNN,PARSE,LAYOUT,RENDER,OUTPUT process;
    class SVG,PNG,HTML,PDF format;

Command-Line Interface

# Generate graph outputs through the CLI
uv run gnn graph --target-dir input/gnn_files --output-dir output

# Or run visualization step directly
uv run python src/main.py --only-steps "8,9" --target-dir input/gnn_files --verbose

Python API

from visualization.processor import process_visualization
from pathlib import Path

# Run visualization on parsed GNN output
process_visualization(
    target_dir=Path("input/gnn_files"),
    output_dir=Path("output"),
    verbose=True
)

Conversion Tools

GNN to Python Converter

The pipeline generates executable code from GNN files via Step 11 (Render):

# Generate code for all supported frameworks
python src/11_render.py --target-dir input/gnn_files --output-dir output --verbose

# Generate for a specific framework
python src/12_execute.py --frameworks "pymdp,jax" --verbose

GNN to LaTeX Converter

The export step (Step 7) generates multiple output formats including LaTeX:

# Export GNN models to multiple formats
python src/7_export.py --target-dir input/gnn_files --output-dir output --verbose

Validation Tools

GNN Validator

The pipeline validates GNN files via Step 5 (Type Checker) and Step 6 (Validation):

# Type checking and validation
python src/5_type_checker.py --target-dir input/gnn_files --output-dir output --strict
python src/6_validation.py --target-dir input/gnn_files --output-dir output --verbose

Common Validation Checks

Syntax compliance with GNN specification
Variable references consistency
Dimensionality compatibility in equations
Proper connection definitions
Ontology mapping validity

Editing Tools

GNN Web Editor

The GNN Web Editor provides a browser-based interface for creating and editing GNN models:

graph TD
    UI[Web Interface] --> EDIT[Edit Model]
    UI --> VIZ[Visualize]
    UI --> SIM[Simulate]
    UI --> SHARE[Share]
    
    EDIT --> SYNTAX[Syntax Highlighting]
    EDIT --> COMPLETE[Auto-Complete]
    EDIT --> CHECK[Real-time Validation]
    
    VIZ --> GRAPH[Connection Graph]
    VIZ --> EQ[Equation Rendering]
    
    SIM --> RUN[Run Simulation]
    SIM --> PLOT[Plot Results]
    
    SHARE --> EXPORT[Export File]
    SHARE --> URL[Share URL]
    
    classDef main fill:#f96,stroke:#333,stroke-width:2px;
    classDef feature fill:#9cf,stroke:#333,stroke-width:1px;
    
    class UI main;
    class EDIT,VIZ,SIM,SHARE,SYNTAX,COMPLETE,CHECK,GRAPH,EQ,RUN,PLOT,EXPORT,URL feature;

Access the web editor at: https://gnn-editor.activeinference.org

IDE Plugins

GNN support is available for various IDEs:

VS Code Extension: Syntax highlighting, validation, and visualization
Jupyter Notebook Extension: Interactive GNN editing and visualization
PyCharm Plugin: GNN integration with Python development

Integration with Active Inference Frameworks

GNN tools integrate with several Active Inference frameworks:

graph LR
    GNN[GNN Tools] --> PYMDP[pymdp]
    GNN --> INFERACTIVELY[inferactively]
    GNN --> PYAIXI[pyaixi]
    GNN --> ACTINFLAB[ActInfLab]
    
    subgraph Integration Features
        EXPORT[Export To Framework]
        IMPORT[Import From Framework]
        VALIDATE[Validate Models]
        SIMULATE[Run Simulations]
    end
    
    PYMDP --- EXPORT
    PYMDP --- IMPORT
    PYMDP --- VALIDATE
    PYMDP --- SIMULATE
    
    classDef tool fill:#f96,stroke:#333,stroke-width:2px;
    classDef framework fill:#9cf,stroke:#333,stroke-width:1px;
    classDef feature fill:#cfc,stroke:#333,stroke-width:1px;
    
    class GNN tool;
    class PYMDP,INFERACTIVELY,PYAIXI,ACTINFLAB framework;
    class EXPORT,IMPORT,VALIDATE,SIMULATE feature;

Integration Examples

PyMDP Integration

# Render and execute via PyMDP backend
python src/11_render.py --target-dir input/gnn_files --output-dir output --verbose
python src/12_execute.py --frameworks "pymdp" --verbose

See PyMDP implementation guide for details on the generated code structure.

Model Repository

The GNN Model Repository contains a collection of pre-built GNN models:

mindmap
  root((GNN Repository))
    Basic Models
      Static Perception
      Dynamic Perception
      Policy Selection
    Cognitive Models
      Working Memory
      Decision Making
      Attention
    Neuroscience Models
      Predictive Coding
      Neural Coordination
      Oscillations
    Embodied Models
      Sensorimotor Integration
      Navigation
      Tool Use

Access the repository at: https://github.com/ActiveInferenceInstitute/GNN-Models

Installation and Setup

Command Line Tools

Basic usage:

# Parse and validate a GNN file
uv run gnn validate --target-dir input/gnn_files

# Parse GNN files
uv run gnn parse --target-dir input/gnn_files --output-dir output

# Visualize a GNN model
uv run gnn graph --target-dir input/gnn_files --output-dir output

# Run the full pipeline
uv run python src/main.py --target-dir input/gnn_files --verbose

Documentation and Resources

Official Documentation

Learning Resources

Community

Step 4 GNN type checker

Tutorial “step 4” lines up with the type checker in Validation Tools and the 5_type_checker.py orchestrator in Complete Pipeline Stages (25 Steps).

GNN type checker and resource estimator

See Validation Tools and resource metrics.

GNN visualization

See Visualization Tools and pipeline Steps 8–9 in Complete Pipeline Stages (25 Steps).

Future Tool Development

Planned tools and features:

timeline
    title GNN Tools Roadmap
    section 2023
        Q3 : Basic Parser : Syntax Validator
        Q4 : Python Code Generator : Command Line Tools
    section 2024
        Q1 : Interactive Visualizer : VS Code Extension
        Q2 : Julia and PyTorch Generators : Web Editor
        Q3 : Model Repository : Template Gallery
        Q4 : Interactive Simulator : Jupyter Integration
    section 2025
        Q1 : AI-Assisted Model Creation : Community Extensions
        Q2 : Model Comparison Tools : Cross-Framework Converter

References

Smékal, J., & Friedman, D. A. (2023). Generalized Notation Notation for Active Inference Models. Active Inference Institute. https://doi.org/10.5281/zenodo.7803328
Active Inference Institute: Generalized Notation Notation (GNN) GitHub Repository
Smith, R., Friston, K.J., & Whyte, C.J. (2022). A step-by-step tutorial on active inference and its application to empirical data. Journal of Mathematical Psychology, 107, 102632.

GNN Processing Pipeline (`src/main.py`)

The GNN project includes a comprehensive 25-step pipeline orchestrated by src/main.py. This main pipeline script is designed to process GNN files through the complete workflow from parsing to execution, visualization, and report generation.

For detailed architecture information, see:

src/AGENTS.md: Complete module registry and architectural patterns
src/README.md: Pipeline safety and reliability documentation
Quickstart Tutorial: Step-by-step tutorial for using the pipeline

Overview

The src/main.py script orchestrates 25 numbered Python scripts (steps 0-24) located in the src/ directory. Each script corresponds to a specific processing stage following the thin orchestrator pattern - delegating core functionality to modular implementations in their associated directories.

The pipeline is designed to be flexible, allowing users to run the entire sequence, skip certain steps, or run only specific steps. It manages configurations like target directories for GNN files and output directories for generated artifacts.

Running the Pipeline

To use the pipeline, navigate to the root directory of the GeneralizedNotationNotation project and execute:

python src/main.py [options]

Command-Line Options

The src/main.py script accepts several command-line arguments:

--target-dir DIR: Specifies the primary target directory for GNN files. Default: input/gnn_files
--output-dir DIR: Defines the base directory where all output files will be saved. Default: output/
--recursive: Enables recursive processing of directories
--skip-steps LIST: Comma-separated list of step numbers to exclude. Example: "3,5,7" or "3_gnn,5_type_checker"
--only-steps LIST: Comma-separated list of step numbers to run exclusively. Example: "3,5,8,11,12"
--verbose: Enables detailed logging output
--strict: Activates strict type checking mode (for step 5)
--estimate-resources: Enables computational resource estimation (for step 5)

View all options: python src/main.py --help

Complete Pipeline Stages (25 Steps)

The GNN processing pipeline consists of exactly 25 steps (0-24), executed in order:

0_template.py (Template Initialization) → src/template/
- Purpose: Pipeline template and initialization
1_setup.py (Environment Setup) → src/setup/
- Purpose: Environment setup, virtual environment management, dependency installation
2_tests.py (Test Suite) → src/tests/
- Purpose: Comprehensive test suite execution
3_gnn.py (GNN Core Processing) → src/gnn/
- Purpose: GNN file discovery, multi-format parsing, and validation
- See: src/gnn/AGENTS.md
4_model_registry.py (Model Registry) → src/model_registry/
- Purpose: Model registry management and versioning
5_type_checker.py (Type Checking) → src/type_checker/
- Purpose: GNN syntax validation and resource estimation
- Supports --strict and --estimate-resources flags
6_validation.py (Validation) → src/validation/
- Purpose: Advanced validation and consistency checking
7_export.py (Export) → src/export/
- Purpose: Multi-format export (JSON, XML, GraphML, GEXF, Pickle)
8_visualization.py (Visualization) → src/visualization/
- Purpose: Graph and matrix visualization generation
- See: src/visualization/AGENTS.md
9_advanced_viz.py (Advanced Visualization) → src/advanced_visualization/
- Purpose: Advanced visualization and interactive plots
10_ontology.py (Ontology Processing) → src/ontology/
- Purpose: Active Inference Ontology processing and validation
- See: src/ontology/AGENTS.md
11_render.py (Code Rendering) → src/render/
- Purpose: Code generation for PyMDP, RxInfer, ActiveInference.jl, DisCoPy, JAX
- See: src/render/AGENTS.md
12_execute.py (Execution) → src/execute/
- Purpose: Execute rendered simulation scripts with result capture
- See: src/execute/AGENTS.md
13_llm.py (LLM Integration) → src/llm/
- Purpose: LLM-enhanced analysis, model interpretation, and AI assistance
- See: src/llm/AGENTS.md
14_ml_integration.py (ML Integration) → src/ml_integration/
- Purpose: Machine learning integration and model training
15_audio.py (Audio Generation) → src/audio/
- Purpose: Audio generation (SAPF, Pedalboard, and other backends)
16_analysis.py (Analysis) → src/analysis/
- Purpose: Advanced analysis and statistical processing
17_integration.py (System Integration) → src/integration/
- Purpose: System integration and cross-module coordination
18_security.py (Security) → src/security/
- Purpose: Security validation and access control
19_research.py (Research Tools) → src/research/
- Purpose: Research tools and experimental features
20_website.py (Website Generation) → src/website/
- Purpose: Static HTML website generation from pipeline artifacts
21_mcp.py (Model Context Protocol) → src/mcp/
- Purpose: Model Context Protocol processing and tool registration
22_gui.py (GUI) → src/gui/
- Purpose: Interactive GUI for constructing/editing GNN models
23_report.py (Report Generation) → src/report/
- Purpose: Comprehensive analysis report generation
24_intelligent_analysis.py (Intelligent Analysis) → src/intelligent_analysis/
- Purpose: AI-enhanced analysis of GNN models and pipeline outputs

MCP Tools (Step 21)

The MCP step exposes every pipeline module as a callable tool. As of v1.5.0 there are 131 real tools (no placeholders, no lambdas) across 38+ domains:

# Run the MCP audit to list all tools
uv run python src/mcp/validate_tools.py
# → generates src/tests/mcp_audit_report.json

# Or via pytest (full suite totals: repository README.md)
uv run pytest src/tests/test_mcp_audit.py -v

Key tool groups:

Domain	Example Tools
audio	`process_audio`, `check_audio_backends`, `get_audio_generation_options`
execute	`execute_gnn_model`, `execute_pymdp_simulation`, `check_execute_dependencies`
llm	`analyze_gnn_with_llm`, `generate_llm_documentation`, `get_llm_providers`
validation	`validate_gnn_file`, `check_schema_compliance`, `get_validation_report`
render	`render_gnn_to_format`, `list_render_frameworks`
gnn	`parse_gnn_content`, `validate_gnn_content`

For the complete tool inventory, see modules/21_mcp.md.

GNN Parser and Type Checker (Steps 3 & 5)

Pipeline Steps: 3_gnn.py and 5_type_checker.py
Functionality: Parse GNN files, validate syntax, check type consistency, and estimate computational resources

Invocation:

# Parse and type-check GNN files
python src/main.py --only-steps "3,5" --target-dir input/gnn_files

# With resource estimation
python src/main.py --only-steps "3,5" --estimate-resources --target-dir input/gnn_files

Outputs: output/3_gnn_output/ and output/5_type_checker_output/

GNN Visualization (Steps 8 & 9)

Pipeline Steps: 8_visualization.py and 9_advanced_viz.py
Functionality: Generate graphical representations, factor graphs, and interactive visualizations

Invocation:

# Generate visualizations
python src/main.py --only-steps "8,9" --target-dir input/gnn_files

Outputs: output/8_visualization_output/ and output/9_advanced_viz_output/

Code Generation and Execution (Steps 11 & 12)

Pipeline Steps: 11_render.py and 12_execute.py
Functionality: Generate executable code for multiple frameworks and run simulations

Invocation:

# Generate and execute code
python src/main.py --only-steps "11,12" --target-dir input/gnn_files

# Execute specific frameworks
python src/12_execute.py --frameworks "pymdp,jax" --verbose

Outputs: output/11_render_output/ and output/12_execute_output/

Post-Simulation Analysis (Step 16)

Pipeline Step: 16_analysis.py
Functionality: Statistical analysis, post-simulation analysis (free energy, policy convergence, state distributions), Active Inference metric computation (entropy, KL divergence, VFE, EFE, information gain), cross-framework comparison, and visualization generation

Invocation:

# Run full render → execute → analyze pipeline
python src/main.py --only-steps "3,11,12,16" --target-dir input/gnn_files --verbose

# Run analysis on existing execution results
python src/main.py --only-steps "16" --verbose

Outputs: output/16_analysis_output/ — includes analysis_results.json, analysis_summary.md, per-model post-simulation analysis, framework-specific visualizations, and cross-framework comparison dashboards
Key Capabilities:
- Per-GNN-file statistical analysis and complexity metrics
- Post-simulation analysis consuming Step 12 execution results
- Active Inference metrics: Shannon entropy, KL divergence, variational free energy, expected free energy, information gain
- Framework-specific visualization generation (PyMDP, RxInfer, ActiveInference.jl, JAX, DisCoPy)
- Cross-framework comparison reports and unified dashboards

Pipeline Examples

# Run full pipeline
python src/main.py --target-dir input/gnn_files --verbose

# Run specific steps only
python src/main.py --only-steps "3,5,7,8,11,12" --verbose

# Skip certain steps
python src/main.py --skip-steps "15,16" --verbose

# Run with specific framework execution
python src/main.py --only-steps "11,12"
python src/12_execute.py --frameworks "lite" --verbose  # PyMDP, JAX, DisCoPy only

For more detailed information on each module, see src/AGENTS.md.

FilesExpand file tree

gnn_tools.md

Latest commit

History

gnn_tools.md

File metadata and controls

GNN Tools and Resources

GNN Tool Ecosystem

Parsing Tools

GNN Parser (Repository CLI)

GNN Parser API Reference

Visualization Tools

GNN Graph Visualizer

Command-Line Interface

Python API

Conversion Tools

GNN to Python Converter

GNN to LaTeX Converter

Validation Tools

GNN Validator

Common Validation Checks

Editing Tools

GNN Web Editor

IDE Plugins

Integration with Active Inference Frameworks

Integration Examples

PyMDP Integration

Model Repository

Installation and Setup

Command Line Tools

Documentation and Resources

Official Documentation

Learning Resources

Community

Step 4 GNN type checker

GNN type checker and resource estimator

GNN visualization

Future Tool Development

References

GNN Processing Pipeline (src/main.py)

Overview

Running the Pipeline

Command-Line Options

Complete Pipeline Stages (25 Steps)

MCP Tools (Step 21)

GNN Parser and Type Checker (Steps 3 & 5)

GNN Visualization (Steps 8 & 9)

Code Generation and Execution (Steps 11 & 12)

Post-Simulation Analysis (Step 16)

Pipeline Examples

GNN Processing Pipeline (`src/main.py`)