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-03-24
- 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 (doc/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 doc/gnn/gnn_syntax.md (v1.1 living spec), doc/gnn/reference/gnn_syntax.md (examples and patterns), and the language hub. - Processing: A single orchestrator (src/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 doc/gnn/reference/architecture_reference.md and doc/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/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: doc/gnn/operations/gnn_troubleshooting.md, doc/gnn/operations/gnn_tools.md.
Orchestrator scripts live in src/; module AGENTS in each folder; per-step documentation in doc/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/doc/AGENTS.md.
Run examples
uv run python src/main.py --target-dir input/gnn_files --verbose
uv run python src/main.py --only-steps "3,5,11,12" --verbose
uv run python src/3_gnn.py --target-dir input/gnn_files --output-dir output --verboseMore command patterns: CLAUDE.md, doc/gnn/operations/gnn_tools.md.
Code generation and execution are organized under src/render/ and src/execute/. Documentation:
| Topic | Link |
|---|---|
| Integration overview | framework_integration_guide.md |
| Implementation patterns | gnn_implementation.md |
| Per-framework index | implementations/README.md |
| PyMDP | pymdp.md, doc/pymdp/gnn_pymdp.md |
| JAX | jax.md |
| RxInfer | rxinfer.md, doc/rxinfer/gnn_rxinfer.md |
| ActiveInference.jl | activeinference_jl.md, activeinference-jl.md |
| NumPyro | numpyro.md |
| PyTorch | pytorch.md |
| DisCoPy | discopy.md, doc/discopy/gnn_discopy.md |
| Stan | stan.md |
| CatColab | catcolab.md, doc/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/cli/ | cli/README.md, cli/AGENTS.md |
| REST API | src/api/ | api/AGENTS.md, doc/api/README.md |
| LSP | src/lsp/ | lsp/AGENTS.md, lsp/README.md |
| MCP tools | src/mcp/ | doc/gnn/mcp/README.md, doc/gnn/mcp/tool_reference.md, doc/gnn/testing/mcp_audit.md |
| Resource | Link |
|---|---|
| Active Inference (conceptual hub in this repo) | doc/active_inference/README.md |
| Learning paths | doc/learning_paths.md |
| Cognitive phenomena examples | doc/cognitive_phenomena/README.md |
| GNN + LLM / neurosymbolic | gnn_llm_neurosymbolic_active_inference.md |
| Ontology system | ontology_system.md |
Hub and manifest
- doc/gnn/README.md — full documentation index (pipelines, language, tutorials, integration).
- doc/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 |
|---|---|
| doc/README.md | Documentation subtree overview |
| doc/INDEX.md | Machine-oriented index |
| doc/START_HERE.md | Guided entry into docs |
| doc/quickstart.md | Step-by-step first pipeline run |
| doc/gnn/README.md | GNN language and pipeline doc hub |
| doc/development/docs_audit.py | Markdown link and AGENTS/README pairing audit |
| doc/development/agents_readme_triple_review.md | Three-pass AGENTS/README review checklist |
| Path | Description |
|---|---|
| src/main.py | Pipeline orchestrator (run full or selected steps) |
| src/AGENTS.md | Per-folder technical notes for src/ |
| src/gnn/, src/render/, src/execute/ | Parse, codegen, simulation |
| src/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 |
| workflows/ci.yml | Tests, Ruff, Bandit on application code paths |
| 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 |
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); paths-ignore: **/*.md, doc/**. workflow_dispatch |
test: matrix Python 3.11 / 3.12 / 3.13 — uv sync --frozen --extra dev, pytest -m "not pipeline and not mcp"; on 3.12 only, MCP tool count must be ≥ 131. lint: Ruff on src/. security: Bandit medium+ on src (JSON artifact upload). |
| docs-audit.yml | push / pull_request to main when paths include **/*.md, doc/**, root AGENTS.md, CLAUDE.md, README.md, SKILL.md, or doc/development/docs_audit.py. workflow_dispatch |
uv sync --frozen --extra dev, uv run python doc/development/docs_audit.py --strict |
| actionlint.yml | push / pull_request when .github/workflows/** changes. workflow_dispatch |
rhysd/actionlint@v1.7.11 |
| dependency-review.yml | pull_request to main. workflow_dispatch |
actions/dependency-review-action@v4 — fail-on-severity: high; denies AGPL licenses listed in the workflow |
| codeql.yml | push / pull_request to main, weekly schedule, workflow_dispatch |
CodeQL init + analyze for Python |
| supply-chain-audit.yml | Weekly cron (0 6 * * 1 UTC), workflow_dispatch |
pip-audit (core): uv export --frozen --no-dev --no-hashes --no-emit-project then OSV pip-audit. pip-audit (all extras, no dev): uv export --frozen --all-extras --no-dev --no-hashes --no-emit-project then same. |
ci.yml ignores Markdown-only and doc/** path changes so documentation edits do not spin the full Python matrix. docs-audit.yml runs when those paths (or the audit script) change, keeping relative links and AGENTS/README pairing checks enforced.
flowchart TB
pr[PR_to_main]
pr --> dep[dependency_review]
pr --> cq[CodeQL]
pr --> ci[CI_tests_Ruff_Bandit_if_not_docs_only]
pr --> da[docs_audit_if_md_doc_or_audit_script]
pr --> al[actionlint_if_workflows_change]
From the repository root:
uv run python doc/development/docs_audit.py --strict
actionlint .github/workflows/*.yml
uv sync --frozen --extra dev
uv run pytest -m "not pipeline and not mcp" --tb=short -q
uv run ruff check src/
uv run bandit -r src -c pyproject.toml --severity-level medium --confidence-level mediumFull local suite (broader than default CI marker filter): uv run pytest src/tests/ -v. Ollama integration tests may need a local daemon; see README.md and pytest.ini.
- doc/style_guide.md — documentation style
- doc/development/README.md — development doc folder