NEURAL_NETWORK_GUIDE.md

# 🧠 Neuronales Netzwerk - Implementierungsanleitung

## Überblick

Ein vollständiges Machine Learning System wurde zu `enhanced_ml_learner.py` hinzugefügt, das neuronale Netzwerke mit Neuronen in Schichten implementiert, die Gewichte und Verzerrungen aus Daten lernen.

## Komponenten

### 1. `NeuralLayer` - Einzelne Neuronenschicht

Eine Schicht mit:
- **Neuronen**: Arrangiert in einer Dimension (output_size)
- **Gewichte**: W (input_size × output_size) - verbinden Eingaben mit Neuronen
- **Verzerrungen**: b (1 × output_size) - Offset für jedes Neuron
- **Aktivierungsfunktionen**: ReLU, Sigmoid, Tanh

**Mathematik:**
```
Output = Activation(Input · W + b)
```

### 2. `SimpleNeuralNetwork` - Mehrschichtiges Netzwerk

Ein komplettes Netzwerk mit:
- Multiple stacked layers
- Forward propagation (Eingabe → Schicht 1 → Schicht 2 → ... → Ausgabe)
- Backward propagation (Fehlergradienten rückwärts)
- Training mit SGD (Stochastic Gradient Descent)

**Eigenschaften:**
- Automatische Gewichtsinitialisierung (Xavier)
- Flexible Netzwerk-Architektur
- Speichern/Laden von Modellen
- Trainingshistorie tracking

### 3. `EnhancedMLLearner` Integration

Die Lernersystem wurde erweitert mit:

```python
# Netzwerk erstellen
network = learner.create_neural_network(
    'task_name',
    [input_size, hidden1, hidden2, ..., output_size],
    learning_rate=0.01
)

# Trainieren
history = learner.train_neural_network(
    'task_name',
    X_train,  # Eingabedaten
    y_train,  # Ziel-Labels
    epochs=20,
    batch_size=32
)

# Vorhersagen
predictions = learner.predict_with_network(
    'task_name',
    X_test
)

# Evaluieren
results = learner.evaluate_network(
    'task_name',
    X_test,
    y_test
)

# Status
status = learner.get_network_status()
```

## Beispiele

### Beispiel 1: Set-Klassifizierung

```python
import numpy as np
from enhanced_ml_learner import SimpleNeuralNetwork

# Erstelle Netzwerk
network = SimpleNeuralNetwork([10, 8, 4, 1], learning_rate=0.1)

# Trainingsdaten
X_train = np.random.randn(100, 10)
y_train = np.random.rand(100, 1)

# Trainiere
history = network.train(X_train, y_train, epochs=20)

# Vorhersage
predictions = network.predict(X_train[:5])
print(predictions)  # Form: (5, 1)
```

### Beispiel 2: Mustererkennung mit Lerner

```python
from enhanced_ml_learner import get_enhanced_ml_learner

learner = get_enhanced_ml_learner()

# Erstelle Netzwerk für Code-Qualitäts-Vorhersage
learner.create_neural_network('code_quality', [20, 16, 8, 1])

# Trainiere auf Features
X = np.random.randn(200, 20)
y = np.random.rand(200, 1)
learner.train_neural_network('code_quality', X, y, epochs=30)

# Mache Vorhersagen
X_test = np.random.randn(10, 20)
result = learner.predict_with_network('code_quality', X_test)
print(result['predictions'])
```

### Beispiel 3: Feedback-basiertes Lernen

```python
from enhanced_ml_learner import get_enhanced_ml_learner

learner = get_enhanced_ml_learner()

# Lerne aus vorhandenem Benutzer-Feedback
result = learner.learn_patterns_from_feedback('response_quality')
print(result['final_accuracy'])  # Trainings-Genauigkeit
```

## Netzwerk-Architektur Empfehlungen

### Kleine Klassifizierung (Binary)
```python
[input_features, 64, 32, 1]  # 3-4 Schichten
```

### Mittlere Klassifizierung (Multi-class)
```python
[input_features, 128, 64, 32, num_classes]  # 4-5 Schichten
```

### Regression
```python
[input_features, 64, 32, 16, 1]  # Mehr versteckte Neuronen
```

### Komplexe Muster
```python
[input_features, 256, 128, 64, 32, 1]  # Tiefere Netzwerke
```

## Hyperparameter-Anleitung

| Parameter | Bereich | Empfohlen | Effekt |
|-----------|---------|-----------|--------|
| Learning Rate | 0.001 - 0.1 | 0.01 | Höher = schneller, aber weniger stabil |
| Epochs | 10 - 100 | 20 | Höher = besser trainiert, aber länger |
| Batch Size | 8 - 64 | 32 | Kleiner = leiser Training, aber langsamer |
| Hidden Units | 4 - 512 | input_size×0.5 | Mehr = komplexer, aber overfitting risiko |

## Training-Tips

1. **Daten normalisieren**: Features sollten ~[−1, 1] oder [0, 1] sein
2. **Epochen monitoren**: Beobachte `losses` für Konvergenz
3. **Genauigkeit prüfen**: Achte auf Trainings- vs. Test-Genauigkeit
4. **Learning rate adjusting**: Wenn Loss stagniert, rate reduzieren
5. **Modelle speichern**: `network.save_model('path.json')`

## Mathematische Details

### Forward Propagation
```
z^l = a^(l-1) · W^l + b^l        (lineare Transformation)
a^l = σ(z^l)                      (Aktivierungsfunktion)
```

### Loss (MSE)
```
L = (1/m) Σ (ŷ - y)²             (Mean Squared Error)
```

### Backward Propagation
```
dL/dW = (1/m) · (a^(l-1))^T · dL/dz^l    (Gewichts-Gradient)
dL/db = (1/m) · Σ dL/dz^l                (Bias-Gradient)
```

### Gewichts-Update
```
W := W - learning_rate · dL/dW
b := b - learning_rate · dL/db
```

## Aktivierungsfunktionen

- **ReLU**: max(0, x) - Default für versteckte Schichten
  - Pros: Schnell, hilft gegen Vanishing Gradients
  - Cons: Dead ReLU Problem

- **Sigmoid**: 1/(1+e^(-x)) - Default für Output (Binary)
  - Pros: Output 0-1, interpretierbar
  - Cons: Vanishing Gradients bei extremen Werten

- **Tanh**: (e^x - e^(-x))/(e^x + e^(-x)) - Alternative
  - Pros: Output -1...1, symmetrisch
  - Cons: Ähnlich zu Sigmoid

## Status und Metriken

Abrufen des gesamten Learning Status:

```python
status = learner.get_overall_learning_status()
print(status['neural_networks'])
print(status['learning_metrics'])
```

Metriken include:
- `context_awareness`: 0-1 (Kontext-Qualität)
- `python_quality`: 0-1 (Code-Qualität)
- `web_learning`: 0-1 (Wissen aus Web)
- `feedback_quality`: 0-1 (Feedback-Qualität)
- `neural_network_accuracy`: 0-1 (NN-Genauigkeit)
- `overall_improvement`: 0-1 (Gesamt-Score)

## Fehlerbehandlung

```python
# Prüfe ob Netzwerk existiert
if not learner.neural_networks.get('my_network'):
    learner.create_neural_network('my_network', [10, 8, 1])

# Speichere Modell
try:
    network.save_model('models/my_network.json')
except Exception as e:
    print(f"Fehler beim Speichern: {e}")
```

## Performance-Optimierung

1. **Batch Processing**: Größere Batches = schneller Training
2. **GPU Support**: Mit NumPy/TensorFlow für GPU-Training möglich
3. **Feature Selection**: Weniger Features = schneller Training
4. **Model Pruning**: Entferne kleine Gewichte nach Training
5. **Quantization**: Konvertiere zu lower precision (z.B. float32→float16)

## Nächste Schritte

1. Test durchführen: `python test_neural_network.py`
2. Eigene Netzwerk-Architektur testen
3. Mit echten Daten trainieren
4. Modelle in Produktion deployen

---

**Status**: ✅ Vollständig funktional und integriert
**Letztes Update**: 2026-03-07