maji-nn 0.1.0

A small neural-network framework built from scratch with NumPy.

Maji

Maji is a small neural-network framework built from scratch with NumPy. It started as a learning project based on the ideas in Neural Networks from Scratch, and this repository is the new home for growing it into a reusable framework.

The current code can build simple feed-forward models for classification, binary classification, and regression. The long-term direction is to grow the core into a clean, well-tested framework that can support deeper model families such as CNNs and transformers, with special attention to performance on Apple silicon.

Install for development

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Install from PyPI

After the first release is published:

python -m pip install maji-nn

The PyPI distribution name is maji-nn, and the Python package import remains maji:

import maji

Quick example

import numpy as np

from maji import (
    Adam,
    CategoricalAccuracy,
    CategoricalCrossEntropyLoss,
    DenseLayer,
    Model,
    ReLU,
    Softmax,
)

x = np.array([[0.0, 0.0], [0.0, 1.0], [1.0, 0.0], [1.0, 1.0]])
y = np.array([0, 1, 1, 0])

model = Model()
model.add(DenseLayer(2, 8))
model.add(ReLU())
model.add(DenseLayer(8, 2))
model.add(Softmax())

model.set(
    loss=CategoricalCrossEntropyLoss(),
    optimizer=Adam(learning_rate=0.01),
    accuracy=CategoricalAccuracy(),
)
model.finalize()
model.train(x, y, epochs=10, print_every=1)

What is included now

• Dense layers
• Dropout
• ReLU, Softmax, Sigmoid, and Linear activations
• Categorical cross entropy, binary cross entropy, mean squared error, and mean absolute error losses
• SGD, AdaGrad, RMSProp, and Adam optimizers
• Classification and regression accuracy helpers
• A sequential Model API with training, evaluation, and model/parameter persistence

Verify

python -m unittest discover -s tests -v

Release

Releases publish to PyPI through GitHub Actions and PyPI Trusted Publishing. The PyPI project is maji-nn; the GitHub workflow is .github/workflows/publish.yml; the GitHub environment is pypi.

To release:

git tag v0.1.0
git push origin v0.1.0
gh release create v0.1.0 --generate-notes

Roadmap

• Split the current single-file core into focused modules
• Improve numerical stability and API consistency
• Add benchmarks for NumPy and Apple silicon acceleration paths
• Add convolutional layers
• Add transformer building blocks
• Add documentation and example notebooks

License

No license has been selected yet. Choose a license before publishing Maji for broad reuse.