NeuronPack Documentation v0.1
A universal, hardware-compiled, composable model container format.

NeuronPack is architecture-agnostic. It works with transformers, SSMs, MoE models, CNNs, or anything you build — including Ω-NEURON. It is a packaging and runtime standard, not a training framework.

Core Philosophy
One model = a folder of independently compiled, self-describing, swappable pieces. Any piece can be replaced, upgraded, pruned, or added without touching anything else.

Think of it like this:

Docker containers for AI components

LEGO where every brick knows its own shape

Git, but for model architecture pieces

Installation
bash
pip install neuronpack        # not published yet — this is the spec
For now, clone and install locally:

bash
git clone https://github.com/yourname/neuronpack
pip install -e .
Dependencies: torch, safetensors, numba, numpy, orjson

The .neuron Folder Structure
text
my_model.neuron/
│
├── manifest.json          ← Wiring diagram: how pieces connect
├── registry.json          ← Expert/module index for fast search
│
├── pieces/
│   ├── <piece_id>.weights     ← Raw weights (safetensors, portable)
│   ├── <piece_id>.meta        ← Interface contract (JSON)
│   └── <piece_id>.kernel      ← Optional: AOT-compiled binary for THIS hardware
│
└── router/
    ├── embeddings.npy         ← Expert position vectors for ANN search
    └── router.so              ← Optional: Numba AOT compiled router
Every model component — an attention head, an SSM layer, an MLP expert, an embedding table, an output head — is a piece. Any architecture maps onto this.

The Three Core Files Per Piece
.weights (always present, portable)
Standard safetensors format. Loads on any hardware. This is the fallback and source of truth.

.meta (always present)
json
{
  "id": "attn_layer_04",
  "role": "attention",
  "architecture": "multi_head_attention",
  "input_shape": [null, 768],
  "output_shape": [null, 768],
  "dtype": "bfloat16",
  "params": 2359296,
  "embedding": [0.12, -0.33, 0.87, "..."],
  "tags": ["short_range", "syntax"],
  "load_count": 0,
  "version": "1.0.0",
  "trainable": true,
  "dependencies": ["embed_layer"],
  "target_hardware": null,
  "compiled": false
}
embedding is a learned vector representing what this piece specializes in — used by the router for semantic search. Works for experts in MoE. For fixed backbone layers, leave it null.

.kernel (optional, hardware-specific)
AOT-compiled binary produced by torch._export.aot_compile. Runs with zero Python overhead. If missing, NeuronPack falls back to .weights + standard PyTorch. If present, it's used automatically when hardware matches.

manifest.json — The Wiring Diagram
This describes how pieces connect. Architecture-agnostic DAG:

json
{
  "model_name": "omega-neuron-300m",
  "architecture_type": "ssm_moe",
  "entry_point": "embed_layer",
  "exit_point": "output_head",
  "execution_mode": "sequential",
  "graph": [
    {"from": "embed_layer",   "to": "ssm_layer_00"},
    {"from": "ssm_layer_00",  "to": "ssm_layer_01"},
    {"from": "ssm_layer_01",  "to": "moe_layer_00"},
    {"from": "moe_layer_00",  "to": "ssm_layer_02"},
    {"from": "ssm_layer_04",  "to": "output_head"}
  ],
  "moe_layers": ["moe_layer_00", "moe_layer_02"],
  "router_type": "ann_embedding",
  "top_k": 2
}
For a transformer, the same format works:

json
{
  "architecture_type": "transformer",
  "graph": [
    {"from": "embed_layer", "to": "attn_layer_00"},
    {"from": "attn_layer_00", "to": "mlp_layer_00"},
    ...
  ]
}
NeuronPack doesn't care what's inside each piece. It only knows: inputs, outputs, and connections.

Python API
Packing a model
python
from neuronpack import NeuronPack

pack = NeuronPack.from_torch_model(
    model=my_model,                    # any nn.Module
    output_path="my_model.neuron",
    manifest=manifest_dict,            # your wiring dict
    compile=False                      # True = AOT compile each piece
)
Or manually add pieces:

python
pack = NeuronPack(path="my_model.neuron")

pack.add_piece(
    piece_id="ssm_layer_00",
    weights=state_dict,                # dict of tensors
    meta={
        "role": "ssm",
        "input_shape": [None, 512],
        "output_shape": [None, 512],
        "dtype": "bfloat16",
        "tags": ["temporal", "fast_state"]
    }
)

pack.save()
Loading a model
python
from neuronpack import NeuronPack

pack = NeuronPack.load("my_model.neuron")

# Load full model (all pieces assembled)
model = pack.assemble()

# Load only specific pieces
embed = pack.get_piece("embed_layer")
expert_7 = pack.get_piece("expert_007")
MoE expert search
python
# Get top-2 experts for a given input embedding
expert_ids = pack.router.search(
    query_embedding=x_embed,    # shape: [d]
    top_k=2
)

# Load and merge them
merged_weights = pack.merge_experts(expert_ids, routing_scores)

# Plug merged weights into MoE layer
model.moe_layer.load_merged(merged_weights)
Swapping a piece (live, no restart)
python
# Replace expert_007 with a new version
pack.swap_piece(
    piece_id="expert_007",
    new_weights=new_state_dict,
    new_meta={"version": "1.0.1", "tags": ["syntax", "python", "rust"]}
)
# Takes effect on next inference call. No model reload.
Adding a new piece (RSI)
python
pack.add_piece(
    piece_id="expert_512",
    weights=new_expert_weights,
    meta={
        "role": "mlp_expert",
        "embedding": learned_embedding.tolist(),
        "tags": ["math", "symbolic"]
    }
)
pack.update_registry()
# Router now considers this expert. Nothing else changes.
Pruning dead pieces
python
# Remove any expert with fewer than 100 lifetime activations
pack.prune(
    role="mlp_expert",
    min_load_count=100
)
AOT Compilation (hardware-specific speedup)
python
# Compile all pieces for current hardware
pack.compile_all(backend="inductor")

# Or compile one piece
pack.compile_piece("ssm_layer_00", backend="inductor")

# Compiled .kernel cached to disk
# Auto-used on next load if hardware matches
Compatibility Matrix
Architecture	Works with NeuronPack?	Notes
Transformer (GPT-style)	✅ Yes	Each attn + MLP block = one piece
Mamba / SSM	✅ Yes	Each SSM block = one piece
Ω-NEURON (yours)	✅ Native	Designed around this
MoE (Mixtral-style)	✅ Yes	Each expert = one piece, router included
CNN	✅ Yes	Each conv block = one piece
Diffusion U-Net	✅ Yes	Each U-Net stage = one piece
LoRA adapters	✅ Yes	Adapter = piece with role: "adapter"
RSI Integration Points
NeuronPack exposes four hooks that an RSI loop can call:

python
pack.on_piece_loaded(callback)     # fires every time a piece is activated
pack.on_piece_idle(callback)       # fires when load_count stagnates
pack.on_manifest_changed(callback) # fires when wiring changes
pack.on_metric_threshold(          # fires when eval metric crosses bound
    metric="perplexity",
    threshold=12.0,
    direction="above",
    callback=trigger_mutation
)
The RSI system sits outside NeuronPack and calls its public API. NeuronPack doesn't do RSI itself — it just makes RSI easy by exposing clean mutation primitives.

What NeuronPack Is NOT
Not a training framework (use PyTorch/HuggingFace for that)

Not a serving framework (use vLLM/TGI for production serving)

Not an optimizer (doesn't touch gradients)

Not architecture-specific (knows nothing about SSMs or transformers internally)

It is purely a format + runtime composition layer that sits between training and inference.

Roadmap
Version	Target
v0.1	Folder format, .meta spec, add_piece, save, load
v0.2	Router (ANN search over embeddings), merge_experts
v0.3	AOT compilation pipeline, .kernel files
v0.4	RSI hooks, on_piece_loaded, prune, swap_piece live
v0.5	Multi-hardware kernel targets (T4, A100, CPU)
v1.0	Stable API, publish to PyPI
Start with v0.1 — just the folder format, the meta spec, and the Python class that reads/writes it. Get that right and everything else builds on top cleanly. The hardest part of this project is not the compilation — it's designing the .meta interface contract so pieces from different models can describe themselves consistently. That's the work worth spending a day on before writing a single line of code.