Metadata-Version: 2.4
Name: ml-linear-lite
Version: 0.1.1
Summary: Machine learning libary built with NumPy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# ml-lite

`ml-lite` ist eine bewusst schlank gehaltene Python-Bibliothek für lineare Regressionsmodelle. Die Algorithmen sind mit NumPy implementiert und eignen sich vor allem dazu, Gradientenabstieg, Regularisierung und Regressionsmetriken nachvollziehbar zu lernen.

> Hinweis: Das Projekt ist ein Lernprojekt und kein Ersatz für produktive Bibliotheken wie scikit-learn.

## Inhalt

- [Funktionen](#funktionen)
- [Voraussetzungen und Installation](#voraussetzungen-und-installation)
- [Schnellstart](#schnellstart)
- [API-Übersicht](#api-übersicht)
- [Metriken](#metriken)
- [Tests und Demo](#tests-und-demo)
- [Projektstruktur](#projektstruktur)
- [Einschränkungen](#einschränkungen)

## Funktionen

| Komponente | Beschreibung |
| --- | --- |
| `LinearRegression` | Lineare Regression ohne Regularisierung |
| `RidgeRegression` | Lineare Regression mit L2-Regularisierung |
| `LassoRegression` | Lineare Regression mit L1-Regularisierung |
| `GradientDescent` | Optimierer für die iterative Aktualisierung von Gewichten und Bias |
| `mse` | Mean Squared Error (mittlerer quadratischer Fehler) |
| `r2` | Bestimmtheitsmaß R² |

Alle Modelle werden per Gradientenabstieg trainiert. Während des Trainings speichert `model.loss` den mittleren quadratischen Fehler jeweils alle 100 Iterationen.

## Voraussetzungen und Installation

Benötigt werden Python 3.10 oder neuer sowie NumPy. Für die Tests wird zusätzlich `pytest` verwendet.

```bash
git clone <repository-url>
cd ml-lite
python -m venv .venv
source .venv/bin/activate       # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
```

Ohne Test-Abhängigkeiten genügt:

```bash
python -m pip install -e .
```

## Schnellstart

```python
import numpy as np

from ml_lite import GradientDescent, RidgeRegression, mse, r2

# Jede Zeile ist eine Beobachtung, jede Spalte ein Merkmal.
X = np.array([[1, 2], [3, 4], [5, 6]])
y = np.array([7, 8, 9])

optimizer = GradientDescent(lr=0.01, n_iter=5_000)
model = RidgeRegression(lambda_=0.5, optimizer=optimizer)

model.fit(X, y)
predictions = model.predict(X)

print("Vorhersagen:", predictions)
print("Gewichte:", model.w)
print("Bias:", model.b)
print("MSE:", mse(y, predictions))
print("R²:", r2(y, predictions))
```

`fit(X, y)` initialisiert die Modellparameter zufällig und optimiert sie für die konfigurierte Anzahl an Iterationen. Daher können die Ergebnisse zwischen Ausführungen leicht variieren. `X` muss zweidimensional sein (`n_beobachtungen × n_merkmale`); `y` enthält einen Zielwert pro Beobachtung.

## API-Übersicht

### Modelle

```python
from ml_lite import LinearRegression, RidgeRegression, LassoRegression
```

| Klasse | Konstruktor | Zweck |
| --- | --- | --- |
| `LinearRegression` | `LinearRegression(optimizer=None)` | Minimiert den quadratischen Vorhersagefehler. |
| `RidgeRegression` | `RidgeRegression(lambda_=0.1, optimizer=None)` | Ergänzt die Optimierung um eine L2-Strafe für große Gewichte. |
| `LassoRegression` | `LassoRegression(lambda_=0.1, optimizer=None)` | Ergänzt die Optimierung um eine L1-Strafe und kann Gewichte in Richtung null drücken. |

Gemeinsame Methoden und Attribute:

| Element | Beschreibung |
| --- | --- |
| `fit(X, y)` | Trainiert das Modell. |
| `predict(X)` | Gibt Vorhersagen zurück; vor dem Training wird ein `ValueError` ausgelöst. |
| `w` | Gewichtsvektor nach dem Training. |
| `b` | Bias (Achsenabschnitt) nach dem Training. |
| `loss` | Liste der während des Trainings aufgezeichneten MSE-Werte. |

### Optimierer

```python
from ml_lite import GradientDescent

optimizer = GradientDescent(lr=0.01, n_iter=1_000)
```

- `lr`: Lernrate. Zu große Werte können dazu führen, dass das Training nicht konvergiert.
- `n_iter`: Anzahl der Aktualisierungsschritte.

Wird kein Optimierer übergeben, verwenden die Modelle `GradientDescent()` mit `lr=0.01` und `n_iter=1000`.

## Metriken

```python
from ml_lite import mse, r2

error = mse(y_true, y_pred)
score = r2(y_true, y_pred)
```

- `mse(y, y_pred)` berechnet den mittleren quadratischen Fehler. Kleinere Werte sind besser; bei perfekten Vorhersagen ist der Wert `0`.
- `r2(y, y_pred)` berechnet R². Bei perfekten Vorhersagen ist der Wert `1`; negative Werte sind bei sehr schlechten Modellen möglich.

## Tests und Demo

Die Beispielanwendung trainiert alle drei Modelle und gibt Vorhersagen, Koeffizienten sowie Metriken aus:

```bash
python test.py
```

Die automatisierten Tests lassen sich nach Installation der Entwicklungsabhängigkeiten ausführen:

```bash
python -m pytest -q
```

## Projektstruktur

```text
ml-lite/
├── ml_lite/
│   ├── __init__.py       # Öffentliche Paket-Schnittstelle
│   ├── linear.py         # Regressionsmodelle
│   ├── metrics.py        # MSE und R²
│   └── optimizer.py      # Gradientenabstieg
├── test/
│   └── test_linear.py    # Unit-Tests
├── pyproject.toml        # Paket- und Abhängigkeitsdefinition
├── test.py               # Ausführbare Demo
└── README.md
```

## Einschränkungen

- Es gibt keine Datenvalidierung, Skalierung oder automatischen Train/Test-Split.
- Die Loss-Historie enthält nur den Fehler ohne Regularisierungsterm.
- Die Modelle sind auf Verständlichkeit und kleine Beispiele ausgelegt; für reale Projekte empfiehlt sich beispielsweise scikit-learn.
- Durch die zufällige Parameterinitialisierung und die fehlende Seed-Steuerung sind Ergebnisse nicht vollständig reproduzierbar.
