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, first of all what a training job on it needs. Every tool but plan, history and model_changes 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.

Before you launch a training job

Call size_training_job before you submit or launch any training job, with the batch size and the card you are about to reserve:

size_training_job { batch_size: 32, gpu: "A100-40" }            # the server's model
size_training_job { model_path: "Model.neurarch.json", batch_size: 256, gpu: "8xH100" }
size_training_job { hf_id: "Qwen/Qwen2.5-0.5B", batch_size: 8, seq_len: 4096 }   # needs --hf

It returns the training peak at that batch (weights and optimizer state, activations, stored attention scores), the smallest card that holds it, the largest batch each card holds, a two-card split when one card does not, one run's cost, and a verdict line you can quote: fits an A100-40 with 22% headroom or will not fit an A100-40: needs ~76 GB ... use A100-80 or batch <= 15. If the verdict says it will not fit, change the batch or the card before launching, not after the OOM.

Pass attention: "eager" if the job uses eager attention; the default is SDPA, which keeps no score matrix. The number is a calibrated estimate under AdamW with bf16 autocast (fitted on 178 measured runs across 41 architectures; held out, the median error is 7% and it flagged 113 of the 131 times a run did not fit a card, where accelerate estimate-memory flagged at most 8; on 25 runs measured after the fit the median miss is 14%), not a measurement; say so when you quote it, and quote the 14% with the 7%.