Metadata-Version: 2.4
Name: euclid-ml
Version: 0.9.1.1
Summary: A simple deep learning framework built on top of numpy/cupy.
Author: Dra3don
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# Euclid

**Euclid** is a lightweight, educational deep learning framework built from the ground up using only **NumPy** or **CuPy**. Its goal is to provide an intuitive, easy-to-use API while exposing the inner workings of modern neural networks.

Unlike large machine learning frameworks, Euclid is designed to be understandable, extensible, and easy to experiment with.

---

## Features

- Automatic differentiation (Autograd)
- CPU (NumPy) and GPU (CuPy) backends
- Sequential model API
- Common neural network layers
  - Dense
  - Conv2D
  - MaxPool2D
  - Flatten
  - Dropout
- Activation functions
  - ReLU
  - Sigmoid
  - Tanh
  - Softmax
- Loss functions
  - Cross Entropy
  - Mean Squared Error (MSE)
  - Huber Loss
- Optimizers
  - SGD
  - RMSProp
  - Adam
- Built entirely in Python using only NumPy/CuPy

---

## Philosophy

Euclid aims to bridge the gap between educational neural network implementations and production machine learning libraries.

The project focuses on:

- Readable source code
- Minimal dependencies
- Performance where possible
- Learning how deep learning frameworks work internally

Whether you're interested in understanding backpropagation, building custom layers, or experimenting with new neural network architectures, Euclid provides a simple and easily editable foundation.

---

## Installation

```bash
pip install euclid-ml
```

---

## Example

```python
import euclid as Euclid

model = Euclid.Sequential([
    Euclid.Dense(784, 128),
    Euclid.ReLU(),
    Euclid.Dense(128, 10),
    Euclid.Softmax(),
])

optimizer = Euclid.Adam(
    model.parameters(),
    learning_rate=1e-3
)

loss = Euclid.CrossEntropy()
```

---

## GPU Support

Euclid can run on either CPU or GPU depending on your configuration.

- **CPU:** NumPy
- **GPU:** CuPy

Simply configure the desired backend and the same code runs on either device.

---

## Why Euclid?

Euclid was created to answer a simple question:

> *How do modern deep learning frameworks actually work under the hood?*

Instead of hiding implementation details behind millions of lines of optimized C++ and CUDA, Euclid implements everything in Python using NumPy and CuPy, making it easy to explore, modify, and extend.

---

## Roadmap

- [x] Automatic differentiation
- [x] Dense layers
- [x] Convolutional neural networks
- [x] GPU backend
- [x] Optimizers
- [ ] Recurrent neural networks
- [ ] Transformers
- [ ] Mixed precision training
- [ ] Model serialization
- [ ] Distributed training

---

## Contributing

Contributions, bug reports, feature requests, and discussions are welcome.

If you'd like to contribute, feel free to open an issue or submit a pull request.

---

## License

This project is licensed under the MIT License.
