Metadata-Version: 2.4
Name: adaiml-tools
Version: 0.1.1
Summary: A Python library
Author: Artheiden
Author-email: Artheiden <artheidendureza@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/artheidendureza/adAI
Project-URL: Documentation, https://adAI.readthedocs.io
Project-URL: Repository, https://github.com/artheidendureza/adAI.git
Project-URL: Issues, https://github.com/artheidendureza/adAI/issues
Keywords: adaiml-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# adAI (adaiml-tools)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11-blue)](https://www.python.org/)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](#)
[![Documentation Status](https://readthedocs.org/projects/adaiml-tools/badge/?version=latest)](https://adAI.readthedocs.io)

**adAI** (published as `adaiml-tools`) is a lightweight, modular, and high-performance machine learning library built entirely from scratch in Python using NumPy. Designed to make AI/ML components accessible, transparent, and easy to understand, adAI lets you construct anything from simple single-layer Perceptrons to Deep Multi-Layer Perceptrons (MLPs) and Convolutional Neural Networks (CNNs).

---

## 🚀 Key Features

- **Built from Scratch**: Zero deep learning framework dependencies—only raw Python and NumPy.
- **Deep MLP & CNN Support**: Full forward and backward propagation implementation for convolutional, dense, batch normalization, and dropout layers.
- **Advanced Optimizers**: Includes `SGD`, `Adam`, `AdamW`, `RAdam`, and `RAdamW`.
- **Learning Rate Schedulers**: Fine-tune training with `StepLR`, `ExponentialLR`, `CosineAnnealingLR`, and `ReduceLROnPlateau`.
- **A Rich Ecosystem of Components**:
  - **Activations**: Sigmoid, ReLU, Tanh, Linear, Softmax.
  - **Losses**: Mean Squared Error (MSE), Mean Absolute Error (MAE), Binary Cross Entropy, Categorical Cross Entropy, Hinge Loss.
  - **Layers**: Dense, Conv2D, Flatten, MaxPool2D, BatchNorm, Dropout.

---

## 📦 Installation

To install the latest stable version from PyPI:

```bash
pip install adaiml-tools
```

For development and building from source:

```bash
git clone https://github.com/artheidendureza/adAI.git
cd adAI
pip install -e ".[dev]"
```

---

## ⚡ Quick Start

adAI provides intuitive generators (`GeneratePerceptron`, `GenerateMLP`, `GenerateCNN`) to instantiate pre-configured networks instantly.

### 1. Single Perceptron
```python
import numpy as np
from adAI import GeneratePerceptron

# Instantiate a Perceptron for binary classification
perceptron = GeneratePerceptron(input_size=5, learning_rate=0.01, epochs=500)

# Generate synthetic train/val/test data
data = perceptron.generate_data(n_train=200, n_val=50, n_test=50)

# Train the model
history = perceptron.train(
    data['X_train'], data['y_train'],
    X_val=data['X_val'], y_val=data['y_val'],
    early_stopping=True, patience=10
)

# Evaluate and predict
metrics = perceptron.evaluate(data['X_test'], data['y_test'])
print(f"Test Accuracy: {metrics['accuracy']:.2%}")
```

### 2. Multi-Layer Perceptron (MLP)
```python
import numpy as np
from adAI import GenerateMLP, StepLR

# Define a 3-layer MLP for classification
mlp = GenerateMLP(
    input_size=10,
    hidden_layers=[64, 32],
    output_size=3,
    learning_rate=0.01,
    epochs=100,
    activation="relu",
    output_activation="softmax",
    dropout=0.2
)

# Set up learning rate scheduling
scheduler = StepLR(step_size=30, gamma=0.5)

# Custom training loop with scheduling
for epoch in range(100):
    mlp.learning_rate = scheduler.get_lr(mlp.learning_rate, epoch)
    history = mlp.train(X_train, y_train, batch_size=32, verbose=False)
```

### 3. Convolutional Neural Network (CNN)
```python
from adAI import GenerateCNN

# Build a CNN with two Conv layers and a Dense head
cnn = GenerateCNN(
    input_shape=(14, 14, 1), # Height, Width, Channels
    conv_layers=[(16, 3), (32, 3)], # (Filters, Kernel Size)
    dense_layers=[32],
    output_size=3,
    learning_rate=0.02,
    epochs=20,
    optimizer="adamw"
)

# Train the CNN
history = cnn.train(X_train, y_train, X_val=X_test, y_val=y_test, batch_size=16)

# Save/Load models easily
cnn.save("saved_cnn.npz")
```

---

## 🛠️ API & Configuration

### Supported Optimizers
Specify any of the following string aliases or class instances:
- `"sgd"` / `SGD`
- `"adam"` / `Adam`
- `"adamw"` / `AdamW`
- `"radam"` / `RAdam`
- `"radamw"` / `RAdamW`

### Supported Loss Functions
- `"mse"` / `mean_squared_error`
- `"mae"` / `mean_absolute_error`
- `"binary_crossentropy"` / `binary_cross_entropy`
- `"categorical_crossentropy"` / `categorical_cross_entropy`
- `"hinge"` / `hinge_loss`

### Learning Rate Schedulers
- `ConstantLR`
- `StepLR(step_size, gamma)`
- `ExponentialLR(gamma)`
- `CosineAnnealingLR(T_max, eta_min)`
- `ReduceLROnPlateau(factor, patience, min_lr)`

---

## 🧪 Testing

We use `pytest` for unit testing and verifying gradient computations. Run tests with coverage using:

```bash
# Run all tests
pytest

# Run tests with HTML coverage report
pytest --cov=src/adAI
```

---

## 🤝 Contributing

Contributions are welcome! Please read our [CONTRIBUTING.md](CONTRIBUTING.md) guide to learn how you can submit Pull Requests, report issues, or suggest new features.

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
