gnn-code-generation - SKILL.md Agent Skill

name: gnn-code-generation description: GNN code generation for simulation frameworks. Use when generating PyMDP, RxInfer.jl, ActiveInference.jl, JAX, DisCoPy, PyTorch, NumPyro, Stan, or bnlearn code from GNN model specifications.

GNN Code Generation / Render (Step 11)

Purpose

Generates executable simulation code from parsed GNN models targeting multiple Active Inference frameworks. Performs pre-render validation of POMDP structures and matrix normalization.

Key Commands

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

# As part of pipeline
python src/main.py --only-steps 11 --verbose

Supported Frameworks

Framework	Language	Subdirectory	Output
PyMDP	Python	`render/pymdp/`	`.py` scripts
RxInfer.jl	Julia	`render/rxinfer/`	`.jl` scripts
ActiveInference.jl	Julia	`render/activeinference_jl/`	`.jl` scripts
JAX	Python	`render/jax/`	`.py` scripts
DisCoPy	Python	`render/discopy/`	`.py` scripts
PyTorch	Python	`render/pytorch/`	`.py` scripts
NumPyro	Python	`render/numpyro/`	`.py` scripts
Stan	Stan	`render/stan/`	`.stan` models
bnlearn	Python	generator-backed	`.py` scripts

API

from render import (
    process_render, render_gnn_spec, get_supported_frameworks,
    validate_render, PyMDPRenderer, JAXRenderer
)

# Render for all frameworks (used by pipeline)
process_render(target_dir, output_dir, verbose=True)

# Render a single GNN spec
result = render_gnn_spec(parsed_spec, framework="pymdp")

# Canonical POMDP rendering
success, message, files = render_gnn_spec(parsed_model, "rxinfer", "output/11_render_output")

# Query supported frameworks
frameworks = get_supported_frameworks()  # ['pymdp', 'rxinfer', ..., 'stan', 'bnlearn']

# Validate render output
validate_render(result, framework="pymdp")

Key Exports

process_render / render_gnn_spec — core rendering functions
PyMDPRenderer / JAXRenderer — renderer classes
get_supported_frameworks / validate_render — utilities

POMDP Processing Pipeline

The render processor follows a structured pipeline for each GNN file:

POMDP Extraction — extracts state spaces (A, B, C, D matrices) from GNN specs
Validation — validates dimensional consistency and completeness
Matrix Normalization — ensures A-matrix columns and B-matrix transition rows sum to 1.0
Framework Code Generation — generates framework-specific executable code
Documentation — creates structured overview of rendering results

Dependencies

# Core rendering (no extra deps needed)
uv sync

# For Julia frameworks (RxInfer.jl, ActiveInference.jl)
# Requires Julia installed and packages available in the active Julia environment
julia --startup-file=no -e 'using RxInfer, ActiveInference, JSON, Distributions, StatsBase'

# For DisCoPy
uv sync --extra graphs

Output

Generated scripts in output/11_render_output/
Per-framework subdirectories: pymdp/, rxinfer/, activeinference_jl/, jax/, discopy/, pytorch/, numpyro/, stan/, bnlearn/
One script per model per framework
Render overview documentation

Troubleshooting

Issue	Solution
Empty render output	Check GNN file has valid `StateSpaceBlock` section
Matrix normalization warnings	Verify matrix dimensions match connections
Julia framework errors	Ensure Julia is installed and packages available

MCP Tools

This module registers tools with the GNN MCP server (see mcp.py):

get_render_module_info
list_render_frameworks
process_render
render_gnn_to_format

References

AGENTS.md — Module documentation
README.md — Usage guide
SPEC.md — Module specification

Documentation

README: Module Overview
AGENTS: Agentic Workflows
SPEC: Architectural Specification
SKILL: Capability API