# 🎨 Code Style Richtlinien für das KI-Cluster

## 1. Ziel
Diese Richtlinie definiert den **einheitlichen Schreib- und Formatierungsstil** für alle Python-Module im KI-Cluster.  
Ziel ist, dass automatisch generierter, manuell geschriebener und überarbeiteter Code **gleich aussieht**, leicht lesbar und wartbar bleibt,  
und durch den Builder-Agent problemlos validiert werden kann.

---

## 2. Allgemeine Formatierung

| Regel | Wert |
|--------|------|
| **Einrückung** | 4 Leerzeichen (keine Tabs) |
| **Zeilenlänge** | max. 100 Zeichen |
| **Kodierung** | UTF-8 |
| **Dateiende** | genau eine Leerzeile |
| **Kommentare** | Deutsch oder Englisch, klar und knapp |
| **Anführungszeichen** | doppelte (`"Text"`) bevorzugt |
| **Importreihenfolge** | Standardbibliothek → Drittpakete → interne Module |
| **Trennung** | jeweils 1 Leerzeile zwischen Funktionsdefinitionen |

Beispiel:
```python
import os
import sys

import requests

from utils.api_client import APIClient
```

---

## 3. Leerzeilen & Struktur

- 2 Leerzeilen zwischen Klassen  
- 1 Leerzeile zwischen Methoden oder Funktionen  
- Keine mehrfachen Leerzeilen  
- Eine Leerzeile am Ende jeder Datei

Beispiel:
```python
class RouterModule:
    pass


class APIModule:
    pass
```

---

## 4. Docstrings

Alle Module, Klassen und Funktionen müssen **Docstrings** besitzen.  
Empfohlenes Format: **Google Style**.

Beispiel (Funktion):
```python
def load_config(file_path: str) -> dict:
    """Lädt eine YAML-Konfigurationsdatei.

    Args:
        file_path (str): Pfad zur Konfigurationsdatei.

    Returns:
        dict: Geladene Konfiguration.
    """
    pass
```

Beispiel (Klasse):
```python
class APIClient:
    """Kommuniziert mit REST-Endpunkten des Systems.

    Attributes:
        base_url (str): Zieladresse des Endpunkts.
    """

    def __init__(self, base_url: str):
        self.base_url = base_url
```

---

## 5. Kommentare

Kommentare sollen **nicht beschreiben, was der Code tut**,  
sondern **warum er es tut**.

Beispiel:
```python
# Schreibt Cache-Datei nur neu, wenn sich Inhalte geändert haben
if new_hash != old_hash:
    write_cache()
```

Regeln:
- Kein redundanter Kommentar wie `# Zählt i um 1 hoch`
- Kommentare beginnen mit Großbuchstaben, enden ohne Punkt.
- Längere Erklärungen über mehrere Zeilen mit `#` beginnen.

---

## 6. Typannotationen

Alle Funktionen und Methoden müssen Typannotationen besitzen.  
Beispiel:
```python
def send_message(target: str, data: dict) -> bool:
    ...
```

Generische Typen werden importiert:
```python
from typing import Any, Optional, List, Dict
```

---

## 7. Konstanten & Variablen

| Typ | Schreibweise | Beispiel |
|------|----------------|-----------|
| Konstanten | `UPPER_CASE` | `MAX_CONNECTIONS = 10` |
| Variablen | `snake_case` | `active_modules = []` |
| Klassenattribute | `self.attribute_name` | `self.router_url = ""` |

---

## 8. Imports

- Keine relativen Importe (`from .core import ...` → ❌)  
- Immer absolute Importe mit vollständigem Pfad ab Projektwurzel  
- Imports werden alphabetisch sortiert

Beispiel:
```python
from utils.api_client import APIClient
from utils.logging_setup import get_logger
```

---

## 9. Fehlerbehandlung

- Fehler **explizit abfangen** (kein `except:` ohne Typ)  
- Logging statt `print()`  
- Möglichst spezifische Fehlertypen verwenden

Beispiel:
```python
try:
    response = requests.get(url)
    response.raise_for_status()
except requests.ConnectionError as e:
    logger.error(f"Verbindungsfehler: {e}")
```

---

## 10. Linter & Formatter

- **Linter:** `flake8`  
- **Formatter:** `black`  
- **Docstring-Prüfer:** `pydocstyle`  
- **Typprüfung:** `mypy`

Beispiel-Aufruf:
```bash
flake8 src/
black src/ --line-length 100
pydocstyle src/
mypy src/
```

Der Builder-Agent führt diese Werkzeuge automatisch aus, bevor Code akzeptiert wird.

---

## 11. Logging-Stil

- Nutze das globale Logging-Setup (`logging_setup.py`)  
- Präfix mit Modulnamen und Funktionskontext  
- Levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

Beispiel:
```python
self.logger.info("[RouterModule] Verbindung erfolgreich hergestellt.")
self.logger.error("[APIModule] Fehler bei der Verarbeitung.")
```

---

## 12. Formatierung von Datenstrukturen

| Struktur | Beispiel |
|-----------|-----------|
| Liste | `users = ["Alice", "Bob", "Eve"]` |
| Dictionary | `config = {"host": "localhost", "port": 5000}` |
| Mehrzeilig (mit Einrückung) | ```python
data = {
    "name": "Cluster",
    "modules": ["Router", "Memory", "API"]
}
``` |

---

## 13. Unit Tests

- Testdateien: `test_<ziel>.py`  
- Testmethoden: `test_<funktion>`  
- Verwende `pytest`  
- Kein direkter `print()` in Tests  
- Tests sind deterministisch (keine Zufallswerte ohne Seeds)

Beispiel:
```python
def test_load_config(tmp_path):
    config_file = tmp_path / "config.yaml"
    config_file.write_text("test: true")
    result = load_config(config_file)
    assert result["test"] is True
```

---

## 14. Builder-Agent Anforderungen

Damit automatisch generierter Code kompatibel bleibt, gilt:
- Builder muss diese Formatierung exakt einhalten  
- Keine abweichenden Imports oder Zeilenlängen  
- Kommentare müssen klar und in Deutsch oder Englisch sein  
- Docstrings **immer vollständig** (Args, Returns)

---

## 15. Zusammenfassung

Durch die konsequente Anwendung dieses Code-Stils wird erreicht:
- Einheitlicher Look & Feel des gesamten Projekts  
- Nahtlose Integration neuer Module durch den Builder-Agent  
- Lesbarkeit, Wartbarkeit und Nachvollziehbarkeit auf Systemebene

---

© 2025 – KI-Cluster Homelab Architektur  
Autor: *[Dein Name oder Alias]*