Neural Nexus Introduction

A NumPy neural network library with a full block system, cognitive architecture, neuromodulatory signaling, and a browser dashboard.

Neural Nexus (nnexus) is a NumPy-based neural network library where every component is visible. You wire blocks together with >> operators, the training loop runs in plain Python, and a biologically-inspired cognitive layer sits on top of standard training. A React + FastAPI browser dashboard lets you train, inspect memory systems, fire neuromodulatory signals, and run spiking simulations interactively.

Requirements

bash

python --version    # 3.9+
python -c "import numpy; print(numpy.__version__)"
# pip install numpy  if missing

No setup.py. Import by pointing Python at the parent directory:

python

import sys
sys.path.insert(0, "/path/to/projects")  # folder containing nnexus/
import nnexus as nx

Your First Network

python

import numpy as np
import nnexus as nx
 
X = np.array([[0,0],[0,1],[1,0],[1,1]], dtype=np.float32)
y = np.array([[0],[1],[1],[0]], dtype=np.float32)
 
blocks = [
    nx.Input(),
    nx.Affine(2, 8, initializer="he_uniform"),
    nx.ReLU(),
    nx.Affine(8, 1),
    nx.Sigmoid(),
    nx.Output(),
]
 
def chain(B):
    for i in range(len(B) - 1):
        B[i] >> B[i + 1]
    for b in B:
        b()
 
model = nx.NeuralNet(blocks, chain, name="XOR")
history = model.fit(X, y, loss=nx.BCE(), optimizer=nx.Adam(lr=0.05), epochs=200)

Expected predictions: close to 0, 1, 1, 0.

Wiring Operators

python

A >> B              # pipe A's output into B
(A | B) >> C        # merge A and B into C
X >> (A, B, C)      # fan out X into A, B, C
Z()                 # execute Z (forward or backward depending on mode)

Training Loop

model.fit() per epoch:

Forward — data flows through blocks left to right
Loss — compare output to target, compute error; seed Output.grad
Backward — error flows right to left (reverses execution log)
Regularizers — L1 / L2 .apply(params) called
Optimizer step — SGD / Adam update weights, skip frozen blocks
Local rules — HebbianRule, OjaRule, or STDPRule for opted-in blocks
model.zero_grad(), record history, run callbacks

Losses, Optimizers, Initializers

Losses:

Class	Use case
`MSE()`	Regression
`BCE()`	Binary classification (use with `Sigmoid`)
`CategoricalCrossEntropy()`	Multi-class (use with `Softmax`)
`Loss(fn, derivative_fn)`	Bring your own

Optimizers:

Class	Parameters
`SGD(lr, momentum=0.0)`	With optional momentum velocity
`Adam(lr=0.001, beta1=0.9, beta2=0.999, eps=1e-8)`	Bias-corrected moments
`Optimizer(update_fn, **hyperparams)`	Bring your own

Initializers (pass as initializer= to Affine / Linear): xavier_uniform, xavier_normal, he_uniform, he_normal, zeros, ones

Regularizers:

python

model.fit(..., regularizers=[nx.L1(0.001), nx.L2(0.01)])

Dashboard

bash

pip install fastapi uvicorn
 
# Terminal 1 — FastAPI backend on port 8642
python dashboard/api.py
 
# Terminal 2 — React frontend
cd dashboard/frontend && bun install && bun run dev
# Open http://localhost:5173

Five tabs:

Tab	Purpose
Trainer	Pick a preset, configure hidden size / filters / LR / epochs, train, view loss curve and predictions
Bridge	Chat with the cognitive bridge (mock or Claude API), see live cognitive state
Neuro	Monitor and manually set neuromodulatory signals (DA, NE, 5HT, ACh)
Memory	Inspect all 5 memory system occupancies, trigger manual reconsolidation
Spiking	Run LIF simulations for T timesteps; spike raster and membrane potential charts

Available training presets: xor, binary_classifier, multiclass, cognitive_xor, cnn_image_binary, cnn_mnist

Built-In Examples

bash

python examples/xor_mlp.py           # XOR: Input → Affine(2,8) → ReLU → Affine(8,1) → Sigmoid → Output
python examples/residual_mlp.py      # residual skip connections
python examples/mnist_mlp.py         # synthetic MNIST-like classification
python examples/cognitive_xor.py     # XOR with Amygdala gate and CognitiveCycle phases
python examples/cnn_mnist.py         # Conv2D → MaxPool2D → Flatten → Affine → Softmax

Tests

bash

python tests/test_v1_smoke.py
python tests/test_gradients.py
python tests/test_blocks.py
python tests/test_cognitive_cycle.py
python tests/test_neuromodulation.py
python tests/test_spiking.py
python tests/test_bridge.py
# 247 tests across 15 files

Next Steps

Core Concepts — full block reference, cognitive architecture, five memory systems, neuromodulatory signals, spiking networks, and the LLM bridge

PreviousArchitecture NextCore Concepts

Was this helpful?

Neural Nexus Introduction

A NumPy neural network library with a full block system, cognitive architecture, neuromodulatory signaling, and a browser dashboard.

Requirements

bash

python --version    # 3.9+
python -c "import numpy; print(numpy.__version__)"
# pip install numpy  if missing

No setup.py. Import by pointing Python at the parent directory:

python

import sys
sys.path.insert(0, "/path/to/projects")  # folder containing nnexus/
import nnexus as nx

Your First Network

python

import numpy as np
import nnexus as nx
 
X = np.array([[0,0],[0,1],[1,0],[1,1]], dtype=np.float32)
y = np.array([[0],[1],[1],[0]], dtype=np.float32)
 
blocks = [
    nx.Input(),
    nx.Affine(2, 8, initializer="he_uniform"),
    nx.ReLU(),
    nx.Affine(8, 1),
    nx.Sigmoid(),
    nx.Output(),
]
 
def chain(B):
    for i in range(len(B) - 1):
        B[i] >> B[i + 1]
    for b in B:
        b()
 
model = nx.NeuralNet(blocks, chain, name="XOR")
history = model.fit(X, y, loss=nx.BCE(), optimizer=nx.Adam(lr=0.05), epochs=200)

Expected predictions: close to 0, 1, 1, 0.

Wiring Operators

python

A >> B              # pipe A's output into B
(A | B) >> C        # merge A and B into C
X >> (A, B, C)      # fan out X into A, B, C
Z()                 # execute Z (forward or backward depending on mode)

Training Loop

model.fit() per epoch:

Forward — data flows through blocks left to right
Loss — compare output to target, compute error; seed Output.grad
Backward — error flows right to left (reverses execution log)
Regularizers — L1 / L2 .apply(params) called
Optimizer step — SGD / Adam update weights, skip frozen blocks
Local rules — HebbianRule, OjaRule, or STDPRule for opted-in blocks
model.zero_grad(), record history, run callbacks

Losses, Optimizers, Initializers

Losses:

Class	Use case
`MSE()`	Regression
`BCE()`	Binary classification (use with `Sigmoid`)
`CategoricalCrossEntropy()`	Multi-class (use with `Softmax`)
`Loss(fn, derivative_fn)`	Bring your own

Optimizers:

Class	Parameters
`SGD(lr, momentum=0.0)`	With optional momentum velocity
`Adam(lr=0.001, beta1=0.9, beta2=0.999, eps=1e-8)`	Bias-corrected moments
`Optimizer(update_fn, **hyperparams)`	Bring your own

Initializers (pass as initializer= to Affine / Linear): xavier_uniform, xavier_normal, he_uniform, he_normal, zeros, ones

Regularizers:

python

model.fit(..., regularizers=[nx.L1(0.001), nx.L2(0.01)])

Dashboard

bash

pip install fastapi uvicorn
 
# Terminal 1 — FastAPI backend on port 8642
python dashboard/api.py
 
# Terminal 2 — React frontend
cd dashboard/frontend && bun install && bun run dev
# Open http://localhost:5173

Five tabs:

Tab	Purpose
Trainer	Pick a preset, configure hidden size / filters / LR / epochs, train, view loss curve and predictions
Bridge	Chat with the cognitive bridge (mock or Claude API), see live cognitive state
Neuro	Monitor and manually set neuromodulatory signals (DA, NE, 5HT, ACh)
Memory	Inspect all 5 memory system occupancies, trigger manual reconsolidation
Spiking	Run LIF simulations for T timesteps; spike raster and membrane potential charts

Available training presets: xor, binary_classifier, multiclass, cognitive_xor, cnn_image_binary, cnn_mnist

Built-In Examples

bash

python examples/xor_mlp.py           # XOR: Input → Affine(2,8) → ReLU → Affine(8,1) → Sigmoid → Output
python examples/residual_mlp.py      # residual skip connections
python examples/mnist_mlp.py         # synthetic MNIST-like classification
python examples/cognitive_xor.py     # XOR with Amygdala gate and CognitiveCycle phases
python examples/cnn_mnist.py         # Conv2D → MaxPool2D → Flatten → Affine → Softmax

Tests

bash

python tests/test_v1_smoke.py
python tests/test_gradients.py
python tests/test_blocks.py
python tests/test_cognitive_cycle.py
python tests/test_neuromodulation.py
python tests/test_spiking.py
python tests/test_bridge.py
# 247 tests across 15 files

Next Steps

Core Concepts — full block reference, cognitive architecture, five memory systems, neuromodulatory signals, spiking networks, and the LLM bridge

PreviousArchitecture NextCore Concepts

Was this helpful?