gnn-environment-setup - SKILL.md Agent Skill

name: gnn-environment-setup description: GNN environment setup and dependency management. Use when configuring the development environment, installing dependencies, managing virtual environments, or troubleshooting dependency issues for the GNN pipeline.

GNN Environment Setup (Step 1)

Purpose

Manages environment configuration, virtual environment creation, and dependency installation for the GNN pipeline. Supports both core and optional dependency groups via uv or pip.

Key Commands

# Run setup step
python src/1_setup.py --target-dir input/gnn_files --output-dir output --verbose

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

# Using uv (recommended)
uv sync                    # Core dependencies (includes Step 12 Python backends: jax, numpyro, torch, discopy)
uv sync --extra dev        # Development tools
uv sync --all-extras       # Everything

Optional Dependency Groups

These groups match [project.optional-dependencies] in pyproject.toml:

Group	Key Packages	Purpose
Core `uv sync`	pymdp, jax, numpyro, torch, discopy, LLM clients, visualization, bnlearn	Standard pipeline runtime
`audio`	librosa, soundfile, pedalboard, pydub	Audio generation
`gui`	gradio, streamlit	GUI interface
`ml-ai`	transformers, scipy, scikit-learn	Machine learning extensions
`graphs`	graphviz	Graphviz bindings
`dev`	pytest-*, mypy, ruff	Development tools
`research`	jupyterlab, sympy, numba, cython	Research tools
`scaling`	dask, distributed, ray	Parallel processing
`all`	Everything above	Full installation

Environment Requirements

Python: 3.11+ (recommended 3.12.x or 3.13.x)
Package manager: uv (recommended) or pip
Core deps: numpy, networkx, pyyaml, jsonschema

Troubleshooting

Issue	Solution
`uv: command not found`	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
PyMDP import fails	`uv sync`
matplotlib missing	`uv sync`
CUDA not detected	Check `torch.cuda.is_available()` after `uv sync`

MCP Tools

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

check_uv_project_status
ensure_directory_exists
find_project_gnn_files
get_standard_output_paths
get_uv_environment_info
install_uv_dependency
setup_uv_project_structure
sync_uv_dependencies

References

AGENTS.md — Module documentation
README.md — Usage guide
SPEC.md — Module specification
../../SETUP_GUIDE.md — Full setup guide
../../pyproject.toml — Dependency definitions

Documentation

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