priornerualnet-mcp
# priorneuralnet-mcp
Domain-Prior Mask-Constrained Neural Networks for `p >> n` tabular data, plus an
MCP server so LLM agents can run the whole loop (validate a prior → benchmark →
inspect concept drivers) over structured tools.
A **prior graph** — an explicit `feature → concept` mapping (JSON or two-column
CSV), e.g. genes → biological pathways, sensors → physical subsystems — is
compiled into a binary mask. Dense layers are constrained to that mask: every
hidden neuron *is* a named domain concept, by construction, not by hope.
## Mathematical formulation
Let `M ∈ {0,1}^{C×F}` be the prior mask (C concepts, F features), with
`M[c,j] = 1` iff feature `j` belongs to concept `c`. A masked layer computes
```
y = (W ⊙ M) x + b, forward uses only effective weights W_eff = W ⊙ M
```
Initialization scales each row by its **own fan-in** `n_c = Σ_j M[c,j]`
(UpperUniform bound `√(6/n_c)`), not the dense fan-in `F` — under-scaling
sparse rows is the classic bug this avoids; a unit test pins it.
Gradient hygiene: a `grad_fn` hook zeroes `∂L/∂W` outside the mask, and after
every optimizer step weights are re-projected (`W ← W ⊙ M`), so AdamW momentum
and weight decay can never leak mass into forbidden connections. Unmapped
(“orphan”) features are not silently dropped: they route through a separate,
small, weight-decayed residual channel — the prior claims they are noise, and
that claim is testable by construction.
The network: `x → MaskedPriorLinear → concept activations h (named) →
optional residual channel → small MLP head → logits`. Baselines built
automatically: a **parameter-matched** `UnconstrainedMLP` (width solved so its
active trainable parameter count hits the prior model's budget) and a standard
full-width MLP. Attributions: Integrated Gradients (pure PyTorch, `n_steps=32`)
with respect to both input features and named concept neurons, giving edge
weights `feature → concept` and `concept → prediction`.
The benchmark: stratified K-fold comparison plus a sample-efficiency learning
curve (25% / 50% / 100% of training data), identical training protocol and
identical hyperparameters for every model. The point of the curves is the
low-data regime: with `n` shrinking, a black box first spends capacity
memorizing noise directions; the prior model's hypothesis class simply does not
contain most of those directions.
## Install
```bash
pip install -e ".[dev]"
```
Python ≥ 3.11. Core: torch, scikit-learn, pandas, pyarrow, pydantic v2, typer,
plotly, jinja2, `mcp[cli]`.
## CLI
```bash
priorneuralnet validate-graph --data data.csv --prior prior.json --target y
priorneuralnet benchmark --data data.csv --prior prior.json --target y \
--n-splits 5 --epochs 60 --output-dir runs
priorneuralnet generate-demo --output-dir examples/demo_run # synthetic p>>n demo
priorneuralnet inspect-concepts --run-id <id> --concept <name> --top-k 10
```
Every command prints JSON on stdout (agent-friendly). Artifacts per run:
`manifest.json` (compact, LLM-sized), `report.html` (Plotly: Sankey
features → concepts → target, generalization-gap and sample-efficiency curves,
concept-importance bars, activation heatmap), `model.pt`,
`concept_activations.parquet`.
## MCP server
```bash
priorneuralnet-mcp # stdio transport
```
Register with any MCP client:
```json
{"mcpServers": {"priorneuralnet": {"command": "priorneuralnet-mcp"}}}
```
Tools: `validate_domain_prior`, `run_priorneuralnet_benchmark`,
`inspect_concept_drivers`. Resource: `priorneuralnet://runs/{run_id}/manifest`.
The engine (`engine/`) never imports `mcp`; the server is a thin JSON-safe
wrapper — a test enforces this boundary.
## Demo
`examples/demo_run/` (generated by `priorneuralnet generate-demo`) contains a
synthetic `p >> n` dataset: N=240 samples, P=300 features grouped into 15 named
pathways, only 3 of which drive the target through a non-linear mixture; the
ground truth is written next to the data (`ground_truth.json`) so recovery can
be checked, not assumed.
## Tests
```bash
pytest -v
```
- `test_masked_gradients.py` — masked connections keep exactly-zero weights and
gradients through AdamW steps; per-row fan-in init; parameter counting.
- `test_prior_graph.py` — mapping formats, validation errors, mask/sparsity stats.
- `test_p_gt_n_benchmark.py` — end-to-end benchmark; injected true pathways
recovered in the top concept attributions; artifact schema.
- `test_mcp_tools.py` — tool/resource registration, round-trips, engine-never-
imports-MCP boundary.
## License
Apache-2.0 (see `LICENSE`, `NOTICE`).TDQS
Scored across 3 tools
The three tools map to distinct workflow stages: validating a prior, running a benchmark, and inspecting a concept's drivers. The only mild overlap is that run_priorneuralnet_benchmark produces concept_drivers.json, which inspect_concept_drivers also surfaces, but targeted inspection remains clearly separate.
All names use snake_case with a leading verb and domain object (validate_domain_prior, run_priorneuralnet_benchmark, inspect_concept_drivers). The pattern is predictable and readable.
Three tools are well-scoped for a focused research server: validate input, execute benchmark, inspect result. No extraneous tools; though minimal, each earns its place.
Core workflow is covered from prior validation through benchmark execution to concept-driver inspection. Minor gaps exist around run management (listing/retrieving prior runs, cleanup) and prior editing, but agents can work around these via returned paths and run ids.