Metadata-Version: 2.4
Name: nn-easy-model
Version: 0.1.2
Summary: A tiny sklearn-style neural network classifier with bundled datasets and train_test_split.
Author-email: Mohamed Boukerche <mohamedboukerche55@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Mohamedboukerche22/easy_model
Project-URL: Repository, https://github.com/Mohamedboukerche22/easy_model
Project-URL: Bug Tracker, https://github.com/Mohamedboukerche22/easy_model/issues
Keywords: neural-network,machine-learning,classifier,train-test-split,csv
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: neuralnetwork-cpp>=0.1
Dynamic: license-file

# easy_model

A tiny, dependency-free, sklearn-style neural network classifier in pure Python,
backed by the fast C++ engine [`neuralnetwork-cpp`](https://pypi.org/project/neuralnetwork-cpp/),
plus pandas-like CSV reading, `train_test_split`, and six bundled classic datasets.

```python
from easy_model import NeuralNetworkCPPClassifier, train_test_split, load_iris
```

## Features

- **NeuralNetworkCPPClassifier** - a scikit-learn compatible classifier
  (`fit` / `predict` / `predict_proba` / `score`, `get_params` / `set_params`).
- **read_csv** - read CSV files (including `.gz`) with pandas-like behavior.
- **train_test_split** - split data into train/test, with shuffle,
  random seeding, and stratification, just like sklearn.
- **Bundled datasets** - iris, wine, breast cancer, diabetes, digits, and
  linnerud, loaded the sklearn way with `return_X_y` support.
- **No pandas or numpy required** - everything is plain Python lists.

## Installation

Install from PyPI (this pulls in the only dependency automatically):

```bash
pip install nn-easy-model
```

Or clone the repository and run it directly:

```bash
git clone https://github.com/Mohamedboukerche22/easy_model.git
cd easy_model
pip install .            # optional: install the package
python main.py           # runs the demos
```

## Quickstart

```python
from easy_model import NeuralNetworkCPPClassifier, train_test_split, load_iris

# 1. Load a dataset
X, y = load_iris(return_X_y=True)

# 2. Split into train / test
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.3, random_state=42, stratify=y,
)

# 3. Train
clf = NeuralNetworkCPPClassifier(
    hidden_layer_sizes=(16, 8),
    learning_rate=0.01,
    max_iter=200,
    batch_size=8,
    random_state=42,
)
clf.fit(X_train, y_train)

# 4. Evaluate and predict
print('train accuracy:', clf.score(X_train, y_train))
print('test  accuracy:', clf.score(X_test, y_test))
print('predicted:', clf.predict(X_test[:3]))
```

## API

### NeuralNetworkCPPClassifier

Main parameters:

| Parameter           | Description                                       |
| ------------------- | ------------------------------------------------- |
| `hidden_layer_sizes` | tuple of hidden layer sizes, e.g. `(128, 64)`    |
| `activation`         | `'relu'`, `'tanh'`, `'sigmoid'`, `'leaky_relu'`, `'linear'` |
| `learning_rate`      | optimizer learning rate                           |
| `max_iter`           | number of training epochs                         |
| `batch_size`         | mini-batch size                                   |
| `optimizer`          | `'adam'`, `'sgd'`, `'momentum'`                   |
| `loss`               | `'cross_entropy'`, `'binary_cross_entropy'`, `'mse'` |
| `shuffle`            | shuffle samples each epoch (bool)                 |
| `random_state`       | seed for reproducibility                          |
| `verbose`            | `1` to print training loss per epoch              |

Methods: `fit(X, y)`, `predict(X)`, `predict_proba(X)`, `score(X, y)`,
`get_params()`, `set_params(**params)`.

Fitted attributes: `classes_`, `n_features_in_`, `n_classes_`, `loss_curve_`,
`history_`, `fit_time_seconds_`.

### read_csv

```python
from easy_model import read_csv, DATA_DIR

header, rows = read_csv(f'{DATA_DIR}/iris.csv')
# header -> [150, 4, 'setosa', 'versicolor', 'virginica']
# rows   -> [[5.1, 3.5, 1.4, 0.2, 0], ...]
```

`read_csv(path, sep=',', header=0)` auto-decompresses `.gz` files, converts
numeric cells to `int`/`float`, and keeps strings as strings. Pass
`header=None` to treat every line as data.

### train_test_split

```python
X_train, X_test, y_train, y_test = train_test_split(
    X, y,
    test_size=0.3,       # fraction, or an int number of samples
    train_size=None,     # mutually exclusive with test_size
    random_state=42,     # reproducibility
    shuffle=True,
    stratify=y,          # keep class proportions in both splits
)
```

### Bundled datasets

| Loader                  | Samples | Features | Target                             |
| ----------------------- | ------- | -------- | ---------------------------------- |
| `load_iris()`           | 150     | 4        | 3-class species                    |
| `load_wine()`           | 178     | 13       | 3-class wine cultivar              |
| `load_breast_cancer()`  | 569     | 30       | binary (malignant/benign)          |
| `load_diabetes()`       | 442     | 10       | regression target                  |
| `load_digits()`         | 1797    | 64       | 10-class digits (0-9)              |
| `load_linnerud()`       | 20      | 3        | multi-output exercise counts       |

Each loader returns a `Bunch` (sklearn-style attributes) or, with
`return_X_y=True`, a `(X, y)` tuple:

```python
bunch = load_wine()
bunch.data, bunch.target, bunch.target_names, bunch.feature_names

X, y = load_wine(return_X_y=True)
```

## Full example

```python
from easy_model import NeuralNetworkCPPClassifier, train_test_split, load_digits

X, y = load_digits(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.25, random_state=0, stratify=y,
)

clf = NeuralNetworkCPPClassifier(
    hidden_layer_sizes=(128, 64), learning_rate=0.003,
    max_iter=10, batch_size=64, random_state=123,
)
clf.fit(X_train, y_train)

print('accuracy:', clf.score(X_test, y_test))
```

## Requirements

- Python 3.8+
- [`neuralnetwork-cpp`](https://pypi.org/project/neuralnetwork-cpp/) (the C++
  backend; the only dependency)

## License

MIT
