Initial commit

00_Globale_Richtlinien/Planung/Code_Style.md

@@ -0,0 +1,251 @@
+# 🎨 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]*

00_Globale_Richtlinien/Planung/Komponenten_Standardstruktur.md

@@ -0,0 +1,471 @@
+# 🧩 Komponenten-Standardstruktur
+
+## 1. Ziel
+Dieses Dokument beschreibt die einheitliche interne Struktur, den Lebenszyklus und die Schnittstellen aller Programme, Module und Komponenten im KI-Cluster.  
+Ziel ist, dass jede Komponente – ob Router, API-Server, Agent, Speicher oder Tool – nach demselben Aufbau funktioniert und sich konsistent starten, erweitern und warten lässt.
+
+---
+
+## 2. Grundprinzip
+
+Jede Komponente ist ein eigenständiges, klar abgegrenztes Modul.  
+Eine Komponente kann:
+- Aufgaben empfangen (z. B. vom Router oder über eine API),
+- eigene Logik ausführen (lokal oder verteilt),
+- Ergebnisse speichern oder weiterleiten,
+- und Statusinformationen melden.
+
+Diese Struktur erlaubt, dass alle Module untereinander austauschbar bleiben und dennoch einheitlich funktionieren.
+
+---
+
+## 3. Standardverzeichnisstruktur
+
+```plaintext
+/<Komponentenname>/
+│
+├── Planung/
+│   ├── Architektur.md
+│   ├── Funktionsbeschreibung.md
+│   └── Kommunikationsschnittstellen.md
+│
+├── Entworfener_Code/
+│   ├── start.py
+│   ├── config.yaml
+│   ├── src/
+│   │   ├── core.py
+│   │   ├── logic.py
+│   │   ├── api_connector.py
+│   │   └── storage.py
+│   ├── tests/
+│   │   └── test_core.py
+│   └── README.md
+│
+└── README.md
+```
+
+---
+
+## 4. Klassenaufbau
+
+Jede Komponente kann, falls objektorientiert entwickelt, auf einer einheitlichen Basisklasse aufbauen, um Grundfunktionen wie Logging, Config-Handling und Kommunikation gemeinsam zu nutzen.
+
+```python
+# Datei: src/core.py
+
+from utils.api_client import APIClient
+from utils.memory_connector import Memory
+from utils.logging_setup import get_logger
+
+class BaseComponent:
+    """Abstrakte Basisklasse für alle Komponenten des KI-Clusters."""
+
+    def __init__(self, name: str):
+        self.name = name
+        self.api = APIClient()
+        self.memory = Memory()
+        self.logger = get_logger(name)
+
+    def register(self):
+        """Registriert die Komponente beim Router oder Systembus."""
+        self.logger.info(f"{self.name} registriert sich beim System.")
+        self.api.register_component(self.name)
+
+    def start(self):
+        raise NotImplementedError("Jede Komponente muss eine start()-Methode implementieren.")
+```
+
+Beispiel für eine spezialisierte Komponente:
+
+```python
+# Beispiel: Router-Modul
+
+from src.core import BaseComponent
+
+class RouterModule(BaseComponent):
+    """Koordiniert Aufgaben zwischen Komponenten und verteilt Anfragen."""
+
+    def start(self):
+        self.logger.info("Router gestartet.")
+        self.listen_for_tasks()
+
+    def listen_for_tasks(self):
+        # Beispielhafte Implementierung
+        self.logger.info("Warte auf eingehende Aufgaben...")
+```
+
+---
+
+## 5. Lebenszyklus einer Komponente
+
+| Phase | Beschreibung |
+|--------|---------------|
+| **Initialisierung** | `start.py` lädt Konfiguration, Logging und die `src/core.py`-Klasse. |
+| **Registrierung** | Komponente meldet sich beim Router oder globalen System an. |
+| **Ausführung** | Logik läuft (z. B. Verarbeitung, API-Handling, Kommunikation). |
+| **Feedback** | Ergebnisse oder Status werden an zentrale Systeme übermittelt. |
+| **Beendigung** | Logs und Speicherzustände werden gesichert, Prozesse sauber beendet. |
+
+---
+
+## 6. Konfigurationsdatei (`config.yaml`)
+
+Beispiel:
+
+```yaml
+component:
+  name: "RouterModule"
+  type: "Systemkomponente"
+  version: "1.0"
+
+communication:
+  router_endpoint: "http://localhost:5000"
+  memory_endpoint: "http://localhost:6000"
+
+logging:
+  level: "INFO"
+  file: "logs/router_module.log"
+```
+
+---
+
+## 7. Gemeinsame Schnittstellen
+
+| Schnittstelle | Zweck | Implementierung |
+|----------------|--------|------------------|
+| **APIClient** | Kommunikation zwischen Komponenten | `utils/api_client.py` |
+| **Memory** | Zugriff auf Wissensspeicher | `utils/memory_connector.py` |
+| **Logger** | Zentrales Logging-System | `utils/logging_setup.py` |
+| **Config Loader** | Einheitliche YAML-Konfiguration | `utils/config_loader.py` |
+
+---
+
+## 8. Kommunikation zwischen Komponenten
+
+Jede Komponente unterstützt mindestens folgende Methoden:
+
+| Methode | Beschreibung |
+|----------|---------------|
+| `register()` | Meldet sich beim zentralen System an |
+| `start()` | Startet die Logik der Komponente |
+| `receive_message(data: dict)` | Empfängt Nachrichten oder Aufgaben |
+| `send_message(data: dict)` | Sendet Ergebnisse oder Events |
+| `shutdown()` | Fährt die Komponente kontrolliert herunter |
+
+---
+
+## 9. Anforderungen an neue Komponenten
+
+Neue Komponenten müssen:
+1. von `BaseComponent` erben (falls OOP),
+2. in `start.py` eingetragen werden,
+3. ihre Konfiguration in `config.yaml` speichern,
+4. Unit-Tests unter `/tests/` bereitstellen,
+5. und saubere Logging- sowie Feedback-Mechanismen besitzen.
+
+---
+
+## 10. Beispielkommunikation
+
+```python
+# Beispiel: Router sendet Aufgabe an API-Modul
+
+task = {
+    "type": "fetch_data",
+    "parameters": {"url": "https://example.com/api"}
+}
+
+api_module.receive_message(task)
+```
+
+Die Komponente führt die Aufgabe aus und antwortet:
+
+```python
+result = {
+    "status": "success",
+    "data": {"records": 24}
+}
+api_module.send_message(result)
+```
+
+---
+
+## 11. Zusammenfassung
+
+Alle Komponenten im System folgen diesem Grundschema.  
+Dadurch wird erreicht, dass:
+- der Router alle Programme gleich ansprechen kann,
+- der Builder-Agent neue Komponenten automatisch integrieren kann,
+- und das gesamte System modular, testbar und erweiterbar bleibt.
+
+---
+© 2025 – KI-Cluster Homelab Architektur  
+Autor: *[Dein Name oder Alias]*
+
+
+### 3.1 Variante: FastAPI-Web-API-Komponente (empfohlen)
+
+Diese Variante verankert die lauffähige Grundstruktur für API-basierte Komponenten mit FastAPI, Logging und Tests.
+
+```plaintext
+/<Komponentenname>/
+│
+├── Planung/
+│   ├── Architektur.md
+│   ├── Funktionsbeschreibung.md
+│   └── Kommunikationsschnittstellen.md
+│
+├── Entworfener_Code/
+│   ├── start.py
+│   ├── requirements.txt
+│   ├── README.md
+│   ├── Dockerfile
+│   ├── docker-compose.yml
+│   ├── app/
+│   │   └── main.py
+│   ├── api/
+│   │   ├── __init__.py
+│   │   ├── router.py
+│   │   └── routes/
+│   │       ├── __init__.py
+│   │       └── execute.py
+│   ├── core/
+│   │   └── base_component.py
+│   ├── config/
+│   │   ├── config.yaml
+│   │   └── logging.yaml
+│   └── tests/
+│       └── test_smoke.py
+│
+└── README.md
+```
+
+Pflichten dieser Struktur:
+- start.py: lädt Konfiguration (config/config.yaml), initialisiert Logging (config/logging.yaml) und startet den FastAPI-Server (uvicorn, optional Factory/Reload).
+- app/main.py: erzeugt die FastAPI-App (create_app), bindet CORS und registriert Router.
+- api/router.py und api/routes/execute.py: Beispiel-Routenstruktur inkl. POST /api/execute sowie GET /health.
+- core/base_component.py: Basisklasse mit Schnittstelle register() und start() für spätere Komponenten.
+- config/logging.yaml: Rotierende Logs (TimedRotatingFileHandler) und zentrale Logger (uvicorn, root).
+- tests/test_smoke.py: pytest-Smoketests für Health-Endpoint und /api/execute.
+- requirements.txt: Abhängigkeiten (u. a. fastapi, uvicorn, pyyaml, pytest, httpx).
+- Dockerfile, docker-compose.yml: Containerisierter Betrieb, Port 8000, Mounts für config/logs.
+- Namens-/Code-Style: snake_case, vollständige Typannotationen, Docstrings gemäß Richtlinien.
+
+Hinweis: Diese Variante ergänzt die allgemeine Standardstruktur aus Abschnitt 3 für API-orientierte Komponenten und dient als verbindlicher Grundstock, auf dem spätere Erweiterungen aufbauen.
+
+
+## 12. Laufzeit-Zielsetzung und Start-Events
+
+- Das Laufzeitprogramm `start.py` bleibt dauerhaft aktiv, da es einen Webserver offen hält und Anfragen entgegennimmt.
+- Der Code ist so vorzubereiten, dass bei eingehenden Start-Events (z. B. POST /start) ein Start-Prozess ausgelöst werden kann.
+- Mehrere Start-Events dürfen möglich sein. Die Entscheidung, ob diese ignoriert, parallel oder in einer Queue verarbeitet werden, wird in dieser Phase bewusst offengelassen und nur als Planungs-Hinweis dokumentiert. Die konkrete Ausführungsstrategie wird später festgelegt.
+
+---
+
+## 13. API-Struktur (Minimal-API unter src/api.py)
+
+- Eine Minimal-API wird in `src/api.py` bereitgestellt.
+- Der Webserver lauscht auf dem in der Konfiguration definierten Port (Standard 8000).
+- `start.py` startet den API-Server und bleibt aktiv, um Anfragen verarbeiten zu können.
+- Die Minimal-API umfasst mindestens:
+  - POST /start: löst den Start-Prozess aus (nicht-blockierend).
+  - Optional GET /health: einfacher Health-Check.
+- Die API darf den Event-Handling-Pfad nicht blockieren; Start-Prozesse werden asynchron oder in eigenen Threads/Tasks ausgeführt.
+
+---
+
+## 14. Globales Konfigurationssystem
+
+Es gibt eine einzige globale Konfiguration. Die Struktur ist folgendermaßen vorgegeben:
+
+```plaintext
++-- globale_configuration
+|   |-- variablename
+|   |   |-- beschreibung erklärung
+|   |   |-- wert
+|
++-- logging
+|   |-- variablename
+|   |   |-- beschreibung erklärung
+|   |   |-- wert
+|
++-- worker
+    |-- variablename
+    |   |-- beschreibung erklärung
+    |   |-- wert
+```
+
+- Diese Konfiguration wird als Python-Struktur in `src/config.py` gepflegt und systemweit verwendet.
+- Zugriff erfolgt zentral über `from src.config import CONFIG`.
+- Der HTTP-Port wird ebenfalls in der globalen Konfiguration gepflegt (z. B. `CONFIG["globale_configuration"]["port"]["wert"]`).
+- Logging-Parameter (Level, Aktivierung, Ausgabeziele) werden ausschließlich über `CONFIG` gesteuert.
+
+---
+
+## 15. Technische Anforderungen (Laufzeit und Architektur)
+
+- Der Webserver darf beim Event-Handling nicht blockieren. HTTP-Handler delegieren die Start-Logik in asynchrone Tasks oder Threads.
+- Start-Routinen laufen asynchron (z. B. asyncio/BackgroundTasks) oder in eigenen Threads, sodass die API schnell antwortet.
+- Logging ist vollständig über die globale Konfiguration steuerbar (z. B. Level, Aktivierung).
+- Modulstruktur:
+  - start.py: Einstiegspunkt (startet Webserver, bleibt aktiv)
+  - src/config.py: zentrale Konfiguration (`CONFIG`)
+  - src/api.py: API-Definition (u. a. POST /start)
+  - src/worker.py: Start-/Arbeitslogik (ausgelöst durch Events)
+  - src/logger.py: Logging-Setup/-Zugriff
+
+---
+
+## 16. Beispiel-/Gerüstcode in Entworfener_Code
+
+Hinweis: Es handelt sich um Struktur- und Ablaufgerüste (kein finaler Code, keine vollständige Implementierung). Ziel ist, Verantwortlichkeiten und Aufrufreihenfolge klar zu dokumentieren.
+
+Beispiel src/config.py:
+```python
+# Globale Konfiguration als Python-Struktur (zentrale Quelle der Wahrheit)
+CONFIG: dict = {
+    "globale_configuration": {
+        "port": {
+            "beschreibung": "HTTP-Port des API-Servers",
+            "wert": 8000,
+        },
+        "environment": {
+            "beschreibung": "Laufzeitumgebung",
+            "wert": "dev",
+        },
+    },
+    "logging": {
+        "enabled": {"beschreibung": "Aktiviert das Logging", "wert": True},
+        "level": {"beschreibung": "Log-Level (z. B. INFO, DEBUG)", "wert": "INFO"},
+    },
+    "worker": {
+        "concurrency": {
+            "beschreibung": "Parallelisierungsgrad (Threads/Tasks), strategische Nutzung offen",
+            "wert": 1,
+        },
+    },
+}
+```
+
+Beispiel src/logger.py:
+```python
+import logging
+from src.config import CONFIG
+
+def get_logger(name: str) -> logging.Logger:
+    logger = logging.getLogger(name)
+    logger.setLevel(getattr(logging, str(CONFIG["logging"]["level"]["wert"]).upper(), logging.INFO))
+    return logger
+```
+
+Beispiel src/worker.py:
+```python
+from typing import Any, Dict
+from src.logger import get_logger
+
+async def trigger_start(payload: Dict[str, Any]) -> None:
+    logger = get_logger("worker")
+    logger.info("Start-Event angenommen (Gerüst).")
+```
+
+Beispiel src/api.py:
+```python
+from typing import Any, Dict, Optional
+from fastapi import FastAPI, BackgroundTasks
+from pydantic import BaseModel
+from src.config import CONFIG
+from src.logger import get_logger
+from src.worker import trigger_start
+
+app = FastAPI(title="Minimal-API (Gerüst)")
+
+class StartRequest(BaseModel):
+    job_id: Optional[str] = None
+    params: Optional[Dict[str, Any]] = None
+
+@app.post("/start")
+async def start_endpoint(req: StartRequest, background: BackgroundTasks) -> Dict[str, str]:
+    logger = get_logger("api")
+    logger.info("Start-Event empfangen (Gerüst).")
+    background.add_task(trigger_start, (req.dict()))
+    return {"status": "accepted"}
+```
+
+Ablauf-Skizze start.py (Beschreibung):
+- Liest die globale Konfiguration aus `src/config.py` (oder eine projektspezifische Quelle).
+- Initialisiert das Logging über `src/logger.py`.
+- Startet den Webserver (z. B. `uvicorn src.api:app`) auf dem in `CONFIG` definierten Port und bleibt aktiv.
+- Nicht-blockierender Betrieb: API antwortet unmittelbar; Arbeitslogik läuft asynchron/parallel.
+
+
+## 17. Restart-/Reload-Funktion (über API)
+
+Ziel
+- Während der Laufzeit soll eine über die API verfügbare Funktion einen Neustart des Python-Prozesses anstoßen, um Konfigurationsänderungen zu übernehmen oder nach Laufzeiterweiterungen sauber durchzustarten.
+- Endpunkte: `POST /restart` sowie Alias `POST /reload`.
+
+Vorgaben
+- Nicht-blockierend: Der HTTP-Handler bestätigt den Auftrag zeitnah und plant den Neustart im Hintergrund mit kurzer Verzögerung (z. B. 300–1000 ms), damit die Antwort noch übertragen werden kann.
+- Prozess-Neustart: Entweder durch einen Vollneustart des Python-Prozesses (z. B. via os.execv) oder durch einen Supervisor (Docker/Compose/Systemd/K8s). In der Scaffold-Phase wird der direkte Prozess-Neustart skizziert.
+- Konfiguration: Optionaler Request-Parameter `delay_ms` zur Steuerung der Verzögerung vor dem Neustart. Weitere Steuerung (z. B. Freigabe-Flag, Backoff) kann über die zentrale `CONFIG` erfolgen.
+- Sicherheit/Robustheit (Hinweise):
+  - Schutz vor Restart-Loops (Backoff/Minimum-Delay).
+  - Optional Authentisierung/Autorisierung für administrative Endpunkte.
+  - Log-Einträge vor Neustart (Grund, Zeitstempel, Kontext).
+- Start-/Mehrfach-Events: Die Strategie für konkurrierende Ereignisse bleibt offen (ignorieren, parallel, Queue). Der Restart-Event ist administrativ und sollte priorisiert behandelt werden, Details werden in der späteren Implementierung festgelegt.
+
+Schnittstellenbeschreibung (Minimal)
+- `POST /restart` → Antwort: `{"status": "scheduled", "delay_ms": <int>}`
+- `POST /reload` → Alias zu `/restart`
+
+Modulzuordnung
+- `src/api.py`: definiert die Endpunkte und plant den Neustart im Hintergrund.
+- `src/worker.py`: enthält die Restart-Hilfsroutine (z. B. `restart_process(reason, delay_seconds)`), die nach einer kurzen Verzögerung den Prozess ersetzt/neustartet.
+- `start.py`: bleibt dauerhaft aktiv; Neustart führt zur Neuinitialisierung inkl. erneuter Auswertung der Konfiguration.
+
+
+## 3.2 Alternative Struktur: app/code-Aufteilung (empfohlen für klare Trennung)
+
+Diese Variante verschiebt den ausführbaren Code, Tests und die API-Struktur unterhalb von `app/code`, während Konfigurationsdateien unter `app/config` leben. Einstiegspunkt und komponentenbezogene README liegen unter `app/`. Artefakte wie Dockerfile, docker-compose und requirements verbleiben auf oberster Ebene von `Entworfener_Code/`.
+
+```plaintext
+Entworfener_Code
+├── app
+│   ├── code
+│   │   ├── api
+│   │   │   ├── __init__.py
+│   │   │   ├── router.py
+│   │   │   └── routes
+│   │   │       ├── execute.py
+│   │   │       └── __init__.py
+│   │   ├── app
+│   │   │   └── main.py
+│   │   ├── core
+│   │   │   └── base_component.py
+│   │   ├── src
+│   │   │   ├── api.py
+│   │   │   ├── config.py
+│   │   │   ├── logger.py
+│   │   │   └── worker.py
+│   │   └── tests
+│   │       └── test_smoke.py
+│   ├── config
+│   │   ├── config.yaml
+│   │   └── logging.yaml
+│   ├── README.md
+│   └── start.py
+├── docker-compose.yml
+├── Dockerfile
+└── requirements.txt
+```
+
+Leitlinien für diese Struktur:
+- `app/start.py` bleibt dauerhaft aktiv (Webserver offen) und liest Konfiguration aus `app/config`.
+- API für Start-Events und Admin-Endpunkte (POST `/start`, `/restart`, `/reload`) liegt in `app/code/src/api.py`. Diese Endpunkte dürfen nicht blockieren; Ausführung wird an `app/code/src/worker.py` delegiert (async/Threads).
+- Zentrale, einzige globale Konfiguration als Python-Struktur in `app/code/src/config.py` (`from src.config import CONFIG`); YAML-Konfigurationsdateien ergänzen diese bei Bedarf (z. B. für externe Operatoren) und werden in `app/config` gepflegt.
+- Logging wird über `CONFIG` gesteuert. Ein Gerüst für Logging-Zugriff liegt in `app/code/src/logger.py`; systemweite Handler/Formatter werden später konsolidiert.
+- Die beispielhafte Router-Struktur für REST-Endpunkte liegt in `app/code/api` und wird in `app/code/app/main.py` eingebunden.
+- Tests unter `app/code/tests` (pytest-Namenskonventionen `test_*.py`).
+
+Hinweis zu Restart/Reload:
+- Die Endpunkte `POST /restart` und `POST /reload` planen (nicht-blockierend) einen Prozessneustart ein, um Konfigurationsänderungen oder Erweiterungen aufzunehmen. Die konkrete Neustartstrategie (Supervisor/execv, Backoff, Auth) ist bewusst noch offen und wird in einer späteren Implementierungsphase festgelegt.

00_Globale_Richtlinien/Planung/Namenskonventionen.md

@@ -0,0 +1,201 @@
+# 🧩 Namenskonventionen für das KI-Cluster
+
+## 1. Ziel
+Diese Richtlinie legt die **einheitlichen Benennungsregeln** für alle Dateien, Klassen, Funktionen, Variablen, Logs, Tests und Ressourcen im gesamten KI-Cluster fest.  
+Durch konsequente Namenskonventionen bleibt das System **verständlich, wartbar und maschinenlesbar** — insbesondere für automatisch arbeitende Module wie den Builder-Agent.
+
+---
+
+## 2. Allgemeine Regeln
+
+- Verwende **englische Begriffe** für Code, Funktionsnamen, Klassen und Module.  
+  (Nur Dokumentation und Beschreibungen dürfen deutsch sein.)  
+- Namen sollen **beschreibend, aber kurz** sein.  
+- Keine Umlaute, Leerzeichen oder Sonderzeichen in Dateinamen.  
+- Trennzeichen je nach Kontext:  
+  - **snake_case** für Dateien, Funktionen und Variablen  
+  - **PascalCase** für Klassen  
+  - **kebab-case** (Bindestriche) für Konfigurations- oder YAML-Dateien  
+  - **UPPER_CASE** für Konstanten  
+
+---
+
+## 3. Dateibenennungen
+
+| Typ | Regel | Beispiel |
+|------|--------|-----------|
+| Python-Dateien | `snake_case.py` | `logic_core.py`, `api_connector.py` |
+| Konfigurationsdateien | `kebab-case.yaml` oder `.json` | `system-config.yaml` |
+| Testdateien | `test_<ziel>.py` | `test_router.py` |
+| Markdown-Dokumente | `PascalCase.md` | `KomponentenStandardstruktur.md` |
+| Logdateien | `<modul>_<datum>.log` | `router_2025-11-12.log` |
+| Diagramme/Bilder | `snake_case.png` / `.svg` | `system_flowchart.svg` |
+
+---
+
+## 4. Klassennamen
+
+- Klassen verwenden **PascalCase**.  
+- Präfixe dürfen die Art der Klasse kennzeichnen (optional).  
+  Beispiele:  
+  - `RouterModule`  
+  - `APIModule`  
+  - `MemoryManager`  
+  - `ConfigLoader`  
+- Abkürzungen vermeiden, außer sie sind allgemein bekannt (`API`, `UI`, `DB`).
+
+Beispiel:
+```python
+class RouterModule:
+    pass
+
+class MemoryManager:
+    pass
+```
+
+---
+
+## 5. Funktions- und Methodennamen
+
+- Verwenden **snake_case** (Kleinbuchstaben + Unterstriche).  
+- Funktionsnamen beschreiben Aktionen.  
+- Wenn eine Funktion boolesche Werte zurückgibt, sollte sie mit `is_`, `has_` oder `can_` beginnen.  
+- Methoden innerhalb von Klassen folgen denselben Regeln.
+
+Beispiele:
+```python
+def load_config():
+    pass
+
+def is_connected():
+    return True
+
+def send_message(data):
+    pass
+```
+
+---
+
+## 6. Variablen
+
+- Verwenden **snake_case**.  
+- Kurze, aber eindeutige Namen.  
+- Keine kryptischen Ein-Buchstaben-Variablen außer in Schleifen (`i`, `j`, `k`).  
+- Bei Konstanten **UPPER_CASE**.  
+
+Beispiele:
+```python
+connection_status = True
+user_name = "admin"
+MAX_RETRIES = 5
+```
+
+---
+
+## 7. Module und Pakete
+
+- Paketnamen immer **kleingeschrieben**.  
+- Zusammengesetzte Namen mit Unterstrich trennen.  
+- Jeder Unterordner mit `__init__.py` kennzeichnet ein Modulpaket.
+
+Beispielstruktur:
+```plaintext
+src/
+├── api_connector/
+│   ├── __init__.py
+│   ├── client.py
+│   └── handler.py
+├── memory_manager/
+│   ├── __init__.py
+│   ├── database.py
+│   └── indexer.py
+└── router/
+    ├── __init__.py
+    └── router_core.py
+```
+
+---
+
+## 8. Tests
+
+- Jeder Testdateiname beginnt mit `test_`.  
+- Testfunktionen folgen der Regel: `test_<funktion>`  
+- Tests dürfen dieselben Bezeichner wie das Zielmodul enthalten.  
+
+Beispiel:
+```python
+def test_load_config():
+    assert load_config() is not None
+```
+
+---
+
+## 9. Logging und Ereignisse
+
+- Logdateien folgen dem Schema: `<komponente>_<YYYY-MM-DD>.log`  
+- Logmeldungen enthalten Präfixe mit Modul- oder Funktionsname.  
+
+Beispiel:
+```python
+self.logger.info("[RouterModule] Verbindung aufgebaut.")
+self.logger.error("[APIModule] Timeout beim Request.")
+```
+
+---
+
+## 10. Konfigurationen & YAML-Schlüssel
+
+- YAML-Schlüssel sind **snake_case**, keine Leerzeichen.  
+- Eindeutige Gruppierung durch logische Sektionen.  
+
+Beispiel:
+```yaml
+system:
+  version: 1.2
+  language: de
+  mode: production
+
+communication:
+  router_endpoint: "http://localhost:5000"
+  memory_endpoint: "http://localhost:6000"
+```
+
+---
+
+## 11. Branch- und Commit-Namen (optional für Git)
+
+| Typ | Format | Beispiel |
+|------|--------|-----------|
+| Feature | `feature/<beschreibung>` | `feature/router-logging` |
+| Fix | `fix/<beschreibung>` | `fix/memory-leak` |
+| Dokumentation | `docs/<bereich>` | `docs/code-style` |
+
+Commit-Messages folgen dem Schema:
+```
+<typ>: <kurze beschreibung>
+
+<optional: längere erklärung>
+```
+
+Beispiel:
+```
+feature: API-Modul erweitert
+
+- Neue Endpunkte für Statusabfragen
+- Logging-System verbessert
+```
+
+---
+
+## 12. Zusammenfassung
+
+Diese Namenskonventionen gewährleisten:
+- Lesbarkeit und Konsistenz im gesamten Projekt  
+- Automatische Code-Generierung ohne Konflikte  
+- Einfaches Wiedererkennen von Modulen und Funktionen  
+- Einheitliches Verhalten in Tests, Logging und Dokumentation
+
+---
+
+© 2025 – KI-Cluster Homelab Architektur  
+Autor: *[Dein Name oder Alias]*