neurarch-mcp: Instructions file for Codex

AGENTS.md

For the agent, not the reader. If you are a coding agent that has landed in this repository or installed this package, this is the short version of what it gives you and, more usefully, of when its answers are worth trusting.

What this is

Two shipped artifacts from one repo:

• neurarch-mcp (npm, Node 20+) — an MCP server that turns a PyTorch model into a structured graph and answers questions about it with computation instead of inference. Every tool but plan and history runs locally, needs no key and no account, and opens no socket.
• neurarch-trace (PyPI, torch >= 2.0) — runs one forward pass and writes the graph with real per-layer shapes.

The rule that matters

Do not act on a finding from a .py file. Trace the model first.

The static parser is the weakest path in this repo and we measured how weak: over 116 model files from 59 popular repositories it returns a graph for 86% and a graph a person would recognise as the model for 41%. Of every block and warn it raised on those graphs, hand-judged, none was a real defect. The cause is structural, not a bug list: the parser reads construction order as data flow and never sees forward(), so residual adds, functional activations and config-selected heads all read as missing or misordered. docs/REAL_REPOS_STUDY.md is the study.

A traced graph has none of that failure mode, because the model has already been built by the time we look at it. The rules themselves are measured on traced graphs: across 264 graphs, every one of the 96 designs the verifier blocked crashed in PyTorch forward, and all 80 it passed ran clean.

So: parse to orient, trace to decide.

Getting a graph, best first

# 1. The script already runs the model: no target, no shapes, no edit.
pip install neurarch-trace
NEURARCH_TRACE=1 python train.py            # writes ./<ClassName>.neurarch.json

# 2. You can name the model and its input.
neurarch-trace my_pkg.model:build --input 1,3,224,224
neurarch-trace hf:Qwen/Qwen2.5-0.5B

# 3. Static, when neither is possible. Orient only.
npx -y neurarch-mcp model.py