Generalized Notation Notation (GNN) is a text-based language for Active Inference generative models. This repository implements a 25-step pipeline (steps 0–24) that discovers and parses GNN sources (Markdown with structured sections), registers models, type-checks and validates them, exports and visualizes structure, attaches ontology annotations, renders executable code for multiple simulation frameworks, executes those scripts, and continues through LLM-assisted analysis, ML integration, audio, statistical analysis, integration/security/research steps, static site generation, MCP exposure, GUI tooling, reporting, and intelligent analysis.
This file is the GitHub-oriented entry point: GNN concepts, deep links into language and pipeline docs, repository layout, CI, and local validation. The narrative overview, badges, publication block, and long examples live in the root README.md.
Last updated: 2026-09-02
- What GNN is
- GNN files and data flow
- Pipeline: all 25 steps
- Render and execute backends
- Interfaces: CLI, API, LSP, MCP
- Active Inference and cognitive modeling docs
- Deep link map (docs/gnn and neighbors)
- Canonical documentation
- Repository map
- Community and policies
- Automation in this folder
- Local validation
- Related tooling docs
- Notation: Models are written as Markdown with labeled sections (for example
## GNNSection,## StateSpaceBlock,## Connections,## InitialParameterization, ontology annotations). The normative and reference material is split across docs/gnn/reference/gnn_syntax.md (v1.6.0 living spec), docs/gnn/tutorials/gnn_examples_doc.md (examples and patterns), and the language hub. - Processing: A single orchestrator (src/gnn/main.py) runs the numbered steps in order (or a subset via
--only-steps/--skip-steps). Step 3 produces parsed representations consumed by type checking, validation, export, visualization, ontology, render, LLM, and related steps; 11 → 12 is the main generate code → run simulation bridge. See docs/gnn/reference/architecture_reference.md and docs/gnn/reference/technical_reference.md. - Architecture: Each step is a thin orchestrator (
src/N_*.py) delegating tosrc/<module>/withAGENTS.mdand usuallyprocessor.py. Diagram and conventions: root AGENTS.md, ARCHITECTURE.md, src/gnn/README.md.
Typical inputs
- Model files under input/gnn_files/ (samples and tests).
- Defaults and knobs in input/config.yaml.
Typical outputs
- Per-step folders under output/ (see root README directory overview). Policy: tracked in git per AGENTS.md / project conventions.
flowchart LR
md[GNN_Markdown] --> s3[Step3_parse]
s3 --> s5[Step5_typecheck]
s3 --> s6[Step6_validate]
s3 --> s8[Step8_viz]
s3 --> s10[Step10_ontology]
s3 --> s11[Step11_render]
s11 --> s12[Step12_execute]
s12 --> s16[Step16_analysis]
s16 --> s23[Step23_report]
Troubleshooting and operator notes: docs/gnn/operations/gnn_troubleshooting.md, docs/gnn/operations/gnn_tools.md.
Orchestrator scripts live in src/; module AGENTS in each folder; per-step documentation in docs/gnn/modules/.
Also documented: init.md (template init), main.md (orchestrator). Infrastructure (not separate numbered steps): pipeline/AGENTS.md, utils/AGENTS.md, api/AGENTS.md, cli/AGENTS.md, lsp/AGENTS.md, src/gnn/doc/AGENTS.md.
Run examples
uv run python src/gnn/main.py --target-dir input/gnn_files --verbose
uv run python src/gnn/main.py --only-steps "3,5,11,12" --verbose
uv run python src/gnn/3_gnn.py --target-dir input/gnn_files --output-dir output --verboseMore command patterns: CLAUDE.md, docs/gnn/operations/gnn_tools.md.
Code generation and execution are organized under src/gnn/render/ and src/gnn/execute/. Documentation:
| Topic | Link |
|---|---|
| Integration overview | framework_integration_guide.md |
| Implementation patterns | gnn_implementation.md |
| Per-framework index | implementations/README.md |
| PyMDP | pymdp.md, docs/pymdp/gnn_pymdp.md |
| JAX | jax.md |
| RxInfer | rxinfer.md, docs/rxinfer/gnn_rxinfer.md |
| ActiveInference.jl | activeinference_jl.md, activeinference-jl.md |
| NumPyro | numpyro.md |
| PyTorch | pytorch.md |
| DisCoPy | discopy.md, docs/discopy/gnn_discopy.md |
| Stan | stan.md |
| CatColab | catcolab.md, docs/other/catcolab/catcolab_gnn.md |
Visualization and export docs: integration/gnn_visualization.md, integration/gnn_export.md. Optional Julia installs for Julia backends are called out in CLAUDE.md and SETUP_GUIDE.md.
| Interface | Code | Documentation |
|---|---|---|
CLI (gnn command) |
src/gnn/cli/ | cli/README.md, cli/AGENTS.md |
| REST API | src/gnn/api/ | api/AGENTS.md, docs/api/README.md |
| LSP | src/gnn/lsp/ | lsp/AGENTS.md, lsp/README.md |
| MCP tools | src/gnn/mcp/ | docs/gnn/mcp/README.md, docs/gnn/mcp/tool_reference.md, docs/gnn/testing/mcp_audit.md |
| Resource | Link |
|---|---|
| Active Inference (conceptual hub in this repo) | docs/active_inference/README.md |
| Learning paths | docs/learning_paths.md |
| Cognitive phenomena examples | docs/cognitive_phenomena/README.md |
| GNN + LLM / neurosymbolic | gnn_llm_neurosymbolic_active_inference.md |
| Ontology system | ontology_system.md |
Hub and manifest
- docs/gnn/README.md — full documentation index (pipelines, language, tutorials, integration).
- docs/gnn/AGENTS.md — subtree manifest and metrics notes.
Language and reference
- gnn_overview.md, about_gnn.md, gnn_paper.md
- reference/gnn_file_structure_doc.md, reference/gnn_schema.md, reference/gnn_type_system.md
- reference/gnn_dsl_manual.md, reference/gnn_standards.md
Tutorials and examples
- tutorials/quickstart_tutorial.md, tutorials/gnn_examples_doc.md
- advanced/advanced_modeling_patterns.md, advanced/gnn_multiagent.md
Operations and quality
- operations/resource_metrics.md, operations/improvement_analysis.md, operations/REPO_COHERENCE_CHECK.md
- testing/README.md, testing/test_patterns.md
Templates (authoring)
| Resource | Description |
|---|---|
| README.md | Main project overview, quick start, pipeline table, examples |
| AGENTS.md | Master registry of all pipeline modules and agent scaffolding |
| CLAUDE.md | Contributor quick reference: commands, architecture, key paths |
| DOCS.md | Consolidated documentation map and diagrams |
| ARCHITECTURE.md | Implementation patterns (thin orchestrators, data flow) |
| SETUP_GUIDE.md | Installation and optional dependency groups |
| CONTRIBUTING.md | How to contribute; includes CI parity commands |
| SECURITY.md | Security policy and reporting |
| CODE_OF_CONDUCT.md | Community standards |
| SUPPORT.md | Help and community links |
| SKILL.md | In-repo skill / tooling notes for agents |
| CHANGELOG.md | Release history |
| CITATION.cff | Citation metadata |
| Path | Role |
|---|---|
| docs/README.md | Documentation subtree overview |
| docs/INDEX.md | Machine-oriented index |
| docs/START_HERE.md | Guided entry into docs |
| docs/quickstart.md | Step-by-step first pipeline run |
| docs/gnn/README.md | GNN language and pipeline doc hub |
| docs/development/docs_audit.py | Markdown link and AGENTS/README pairing audit |
| docs/development/agents_readme_triple_review.md | Three-pass AGENTS/README review checklist |
| Path | Description |
|---|---|
| src/gnn/main.py | Pipeline orchestrator (run full or selected steps) |
| src/gnn/AGENTS.md | Per-folder technical notes for src/ |
| src/gnn/, src/gnn/render/, src/gnn/execute/ | Parse, codegen, simulation |
| tests/ | Pytest suite |
| input/gnn_files/ | Sample GNN models; input/config.yaml defaults |
| output/ | Pipeline outputs (tracked per repo policy) |
| pyproject.toml | Dependencies and tool config |
| pytest.ini | Test markers and pytest settings |
| Link | Use |
|---|---|
| Issues | Bugs and tracked work |
| Discussions | Ideas and Q&A |
| Contributors | Contribution history |
Publication reference and DOI appear in the root README.md (Overview).
This directory holds Dependabot configuration and GitHub Actions workflows. Workflow-focused summary: workflows/README.md. Maintainer guardrails: AGENTS.md.
| Path | Role |
|---|---|
| dependabot.yml | Dependabot version updates (pip + GitHub Actions) |
| AGENTS.md | Permissions, standards, maintenance checklist |
| README.md | This hub |
| SPEC.md | Folder specification |
| workflows/ci.yml | Tests (Ruff/mypy/doc audits on 3.12), v3 orchestration acceptance, Bandit SARIF |
| workflows/mcp-audit.yml | MCP tool count audit (push/PR to main) |
| workflows/full-extras.yml | Weekly all-extras install + full test suite |
| workflows/docs-audit.yml | Strict Markdown / doc structure audit |
| workflows/actionlint.yml | Workflow YAML lint |
| workflows/dependency-review.yml | PR dependency and license gate |
| workflows/codeql.yml | CodeQL static analysis (Python) |
| workflows/supply-chain-audit.yml | Scheduled pip-audit on lockfile exports |
| workflows/README.md | Workflow table and local actionlint |
| workflows/AGENTS.md | Workflow agent guide |
| workflows/SPEC.md | Workflow folder specification |
Configured in dependabot.yml:
- pip (
directory: /): weekly Monday 06:00 UTC, target branchmain, groupedpip-dependenciespattern*, labelsdependencies/python, commit prefixdeps(pip), up to 15 open PRs, auto rebase. - github-actions (
directory: /): weekly Monday 06:30 UTC, same branch, commit prefixdeps(actions), labelsdependencies/github-actions, auto rebase.
| Workflow | Triggers | What it runs |
|---|---|---|
| ci.yml | push and pull_request to main (opened, synchronize, reopened, ready_for_review); no path filter — runs on doc-only changes too. workflow_dispatch |
test: matrix 3.11 / 3.12 / 3.13; Python 3.12 also runs Ruff format/check over src scripts, terminology audits, docs audit, documentation contract audit (check_doc_contracts.py), GNN doc patterns, mypy, collect-only, focused PyMDP/POMDP tests, MCP ≥ 140, and the v3 orchestration acceptance gate. All matrix entries run pytest with coverage, JUnit/summary. security: Bandit SARIF → upload-sarif + artifact. |
| mcp-audit.yml | push / pull_request to main. workflow_dispatch |
MCP tool count ≥ 140 via tests.mcp.test_mcp_audit.count_mcp_tools. |
| full-extras.yml | Weekly cron Sunday 06:00 UTC (0 6 * * 0). workflow_dispatch |
uv sync --frozen --all-extras, optional-import validation (audio, GUI, research/scaling), full pytest suite under all extras (Python 3.12). |
| docs-audit.yml | push / pull_request to main when paths include **/*.md, docs/**, root AGENTS.md, CLAUDE.md, README.md, SKILL.md, or docs/development/docs_audit.py. workflow_dispatch |
uv sync --frozen --extra dev, strict docs audit with anchors, repository/doc terminology audits, and GNN doc-pattern audit. |
| actionlint.yml | push / pull_request when .github/workflows/** changes. workflow_dispatch |
rhysd/actionlint@v1.7.12 |
| dependency-review.yml | pull_request to main. workflow_dispatch |
fail-on-severity: high, AGPL deny list, PR comment summary on failure (fork limitations). |
| codeql.yml | push / pull_request (paths-ignore doc-only), weekly schedule, workflow_dispatch |
init → uv sync --frozen --extra dev → analyze (Python). |
| supply-chain-audit.yml | Weekly cron (0 6 * * 1 UTC), workflow_dispatch |
pip-audit (core) and pip-audit (all extras, no dev) via frozen uv export; OSV; job summaries. |
Fork PRs: Dependency review may be limited for PRs from forks; see the link in the dependency-review row above.
ci.yml runs on every push/PR to main with no path filter, and its 3.12 job already includes the doc audits. docs-audit.yml is path-filtered (**/*.md, docs/**, root AGENTS.md/CLAUDE.md/README.md/SKILL.md, docs/development/docs_audit.py) and runs the same audit set in a lean single job, so doc-only changes get a fast, focused signal.
flowchart TB
pr[PR_to_main]
pr --> dep[dependency_review]
pr --> cq[CodeQL]
pr --> ci[CI_full_matrix_no_path_filter]
pr --> mc[mcp_audit_tool_count]
pr --> da[docs_audit_if_md_doc_or_audit_script]
pr --> al[actionlint_if_workflows_change]
From the repository root:
actionlint .github/workflows/*.yml
uv sync --frozen --extra dev
uv run --extra dev ruff format --check src scripts
uv run --extra dev ruff check src scripts
uv run --extra dev python scripts/check_repo_terminology.py --strict
uv run --extra dev python scripts/check_maintained_doc_terms.py --strict
uv run --extra dev python docs/development/docs_audit.py --strict --check-anchors --no-write
uv run --extra dev python scripts/check_gnn_doc_patterns.py --strict
uv run --extra dev mypy src --show-error-codes
# Optional: external-URL health across maintained docs (informational — bot-blocked
# hosts like crates.io/paperswithcode can false-positive; not wired into CI)
uv run --extra dev python scripts/check_external_links.py
uv run --extra dev bandit -r src -c pyproject.toml -q
uv run --extra dev python -m pytest --collect-only tests/ -q --tb=no \
--ignore=tests/llm/test_llm_ollama.py \
--ignore=tests/llm/test_llm_ollama_integration.py
uv run --extra dev python -m pytest \
tests/execute/test_pymdp_contracts.py \
tests/execute/test_discrete_models_pymdp.py \
tests/visualization/test_visualization_matrices.py \
-q --tb=short
uv run --extra dev python -m pytest -m "not pipeline and not mcp" --tb=short -q
# Same output as CI security job (SARIF for artifacts / code scanning):
# uv run --extra dev bandit -r src -c pyproject.toml --severity-level medium --confidence-level medium -f sarif -o bandit-results.sarifFull local suite (broader than default CI marker filter): uv run --extra dev python -m pytest tests/ -q --tb=no --ignore=tests/llm/test_llm_ollama.py --ignore=tests/llm/test_llm_ollama_integration.py. Ollama integration tests may need a local daemon; see README.md and pytest.ini.
- docs/style_guide.md — documentation style
- docs/development/README.md — development doc folder