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
  • Directory index
  • Dependabot
  • Workflows
  • Why CI and docs-audit split
  • Automation on a typical PR
• 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 to src/<module>/ with AGENTS.md and usually processor.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 --verbose

More command patterns: CLAUDE.md, doc/gnn/operations/gnn_tools.md.

Code generation and execution are organized under src/render/ and src/execute/. Documentation:

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.

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)

• doc/templates/README.md

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.

Configured in dependabot.yml:

• pip (directory: /): weekly Monday 06:00 UTC, target branch main, grouped pip-dependencies pattern *, labels dependencies / python, commit prefix deps(pip), up to 15 open PRs, auto rebase.
• github-actions (directory: /): weekly Monday 06:30 UTC, same branch, commit prefix deps(actions), labels dependencies / github-actions, auto rebase.

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 medium

Full 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