Metadata-Version: 2.4
Name: maji-nn
Version: 0.1.0
Summary: A small neural-network framework built from scratch with NumPy.
Author: Morgan Githinji
Project-URL: Homepage, https://github.com/mgithinji/maji
Project-URL: Repository, https://github.com/mgithinji/maji
Project-URL: Issues, https://github.com/mgithinji/maji/issues
Keywords: deep-learning,machine-learning,neural-networks,numpy
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=2.0

# 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

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

## Install from PyPI

After the first release is published:

```bash
python -m pip install maji-nn
```

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

```python
import maji
```

## Quick example

```python
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

```bash
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:

```bash
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.
