Skip to main content
Glama
priornerualnet-mcp

priornerualnet-mcp

by LatentVirtue

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.

Related MCP server: groundtruth-mcp

Install

pip install -e ".[dev]"

Python ≥ 3.11. Core: torch, scikit-learn, pandas, pyarrow, pydantic v2, typer, plotly, jinja2, mcp[cli].

CLI

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

priorneuralnet-mcp        # stdio transport

Register with any MCP client:

{"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

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).

Available Tools

3 tools
inspect_concept_driversC

Return a concept's attribution rank plus its top-k feature drivers.

Inputs: run_id (required), concept_name (required), top_k, output_dir.

run_priorneuralnet_benchmarkB

Benchmark the prior-constrained network against parameter-matched MLPs.

Writes artifacts under <output_dir>/<run_id>/ (manifest.json, report.html, concept_activations.parquet, final_model.pt, concept_drivers.json) and returns the run id, verdict, per-model val scores and a pointer to the full manifest.

Inputs: data_path (required), prior_path (required), target_column (required), epochs, +3 more.

validate_domain_priorB

Check a dataset + feature->concept prior and report graph statistics.

Returns {valid: bool, stats: {...}} or {valid: false, error: ...}. Stats include sparsity density, per-concept fan-in and orphan features.

Inputs: data_path (required), prior_path (required), target_column (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 3 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables LLMs to orchestrate AI agents and tasks, inspect DAG workflows, monitor cluster metrics, and perform safe database queries and statements through standardized MCP tools.
      189
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-compatible clients to access model registry, prediction logging, drift detection, bias/fairness auditing, compliance and governance queries, explanation generation, LLM/RAG monitoring, content safety, alert management, multi-agent workflow tracking, and performance metrics through 197 tools across 18 domains. Supports stdio and hosted Streamable HTTP transports, plus MCP Apps interactive audit cards.
      35 PyPI
      MIT