From 6fddc00ac6443d4bebd8d29bf4e0d8282915cd63 Mon Sep 17 00:00:00 2001 From: madgerm Date: Wed, 12 Nov 2025 11:49:38 +0100 Subject: [PATCH] Initial commit --- .../Entworfener_Code/Dockerfile | 33 ++ .../Entworfener_Code/app/code/app/main.py | 59 +++ .../Entworfener_Code/app/config/config.yaml | 36 ++ .../Entworfener_Code/app/config/logging.yaml | 57 +++ .../Entworfener_Code/app/start.py | 161 ++++++ .../Entworfener_Code/requirements.txt | 15 + 00_Globale_Richtlinien/Planung/Code_Style.md | 251 ++++++++++ .../Planung/Komponenten_Standardstruktur.md | 471 ++++++++++++++++++ .../Planung/Namenskonventionen.md | 201 ++++++++ 00_Globale_Richtlinien/README.md | 93 ++++ roadmap_readme.md | 190 +++++++ 11 files changed, 1567 insertions(+) create mode 100644 00_Globale_Richtlinien/Entworfener_Code/Dockerfile create mode 100644 00_Globale_Richtlinien/Entworfener_Code/app/code/app/main.py create mode 100644 00_Globale_Richtlinien/Entworfener_Code/app/config/config.yaml create mode 100644 00_Globale_Richtlinien/Entworfener_Code/app/config/logging.yaml create mode 100644 00_Globale_Richtlinien/Entworfener_Code/app/start.py create mode 100644 00_Globale_Richtlinien/Entworfener_Code/requirements.txt create mode 100644 00_Globale_Richtlinien/Planung/Code_Style.md create mode 100644 00_Globale_Richtlinien/Planung/Komponenten_Standardstruktur.md create mode 100644 00_Globale_Richtlinien/Planung/Namenskonventionen.md create mode 100644 00_Globale_Richtlinien/README.md create mode 100644 roadmap_readme.md diff --git a/00_Globale_Richtlinien/Entworfener_Code/Dockerfile b/00_Globale_Richtlinien/Entworfener_Code/Dockerfile new file mode 100644 index 0000000..5dc2103 --- /dev/null +++ b/00_Globale_Richtlinien/Entworfener_Code/Dockerfile @@ -0,0 +1,33 @@ +# syntax=docker/dockerfile:1 +ARG PYTHON_VERSION=3.11 + +FROM python:${PYTHON_VERSION}-slim AS base + +ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 + +# Optional: Systemabhängigkeiten (Minimalsatz) +RUN apt-get update && apt-get install -y --no-install-recommends \ + ca-certificates curl build-essential \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /app + +# Dependencies zuerst kopieren für bessere Layer-Caching-Effizienz +COPY requirements.txt /app/requirements.txt +RUN pip install --no-cache-dir -r /app/requirements.txt + +# Anwendungscode +COPY . /app + +# Non-root User +RUN useradd -m appuser && chown -R appuser:appuser /app +USER appuser + +# Standard-Config-Pfad für die App-Factory (neue Struktur unter /app/app/config) +ENV APP_CONFIG_PATH=/app/app/config/config.yaml + +EXPOSE 8000 + +# Start über Uvicorn-Factory aus neuer Struktur: app/start.py stellt app_factory() bereit +CMD ["uvicorn", "app.start:app_factory", "--factory", "--host", "0.0.0.0", "--port", "8000"] \ No newline at end of file diff --git a/00_Globale_Richtlinien/Entworfener_Code/app/code/app/main.py b/00_Globale_Richtlinien/Entworfener_Code/app/code/app/main.py new file mode 100644 index 0000000..a37c1aa --- /dev/null +++ b/00_Globale_Richtlinien/Entworfener_Code/app/code/app/main.py @@ -0,0 +1,59 @@ +from typing import Any, Dict, List, Optional + +from fastapi import FastAPI +from fastapi.middleware.cors import CORSMiddleware + + +def create_app(config: Optional[Dict[str, Any]] = None) -> FastAPI: + """ + Erzeugt und konfiguriert die FastAPI-Anwendung. + + Args: + config: Konfigurations-Dictionary (z. B. aus app/config/config.yaml geladen). + + Returns: + FastAPI: Konfigurierte FastAPI-App. + """ + cfg: Dict[str, Any] = config or {} + meta: Dict[str, Any] = cfg.get("meta", {}) + app_cfg: Dict[str, Any] = cfg.get("app", {}) + cors_cfg: Dict[str, Any] = cfg.get("cors", {}) + + app = FastAPI( + title=app_cfg.get("name", "entworfener_code_service"), + version=str(meta.get("version", "0.1.0")), + docs_url="/docs", + redoc_url="/redoc", + ) + + # CORS + allow_origins: List[str] = cors_cfg.get("allow_origins", ["*"]) + allow_credentials: bool = bool(cors_cfg.get("allow_credentials", True)) + allow_methods: List[str] = cors_cfg.get("allow_methods", ["*"]) + allow_headers: List[str] = cors_cfg.get("allow_headers", ["*"]) + + app.add_middleware( + CORSMiddleware, + allow_origins=allow_origins, + allow_credentials=allow_credentials, + allow_methods=allow_methods, + allow_headers=allow_headers, + ) + + # Router registrieren (unter app/code/api) + try: + from api.router import api_router + + app.include_router(api_router, prefix="/api") + except Exception: + # Router existiert evtl. noch nicht beim ersten Scaffold + pass + + @app.get("/health", tags=["health"]) + async def health() -> Dict[str, str]: + """ + Einfache Health-Check-Route. + """ + return {"status": "ok"} + + return app \ No newline at end of file diff --git a/00_Globale_Richtlinien/Entworfener_Code/app/config/config.yaml b/00_Globale_Richtlinien/Entworfener_Code/app/config/config.yaml new file mode 100644 index 0000000..6df930d --- /dev/null +++ b/00_Globale_Richtlinien/Entworfener_Code/app/config/config.yaml @@ -0,0 +1,36 @@ +# Application settings +app: + name: "entworfener_code_service" + host: "0.0.0.0" + port: 8000 + reload: true + +# Logging settings +logging: + level: "INFO" + config_file: "config/logging.yaml" + +# CORS settings +cors: + allow_origins: + - "*" + allow_credentials: true + allow_methods: + - "*" + allow_headers: + - "*" + +# Paths (relativ zu app/) +paths: + log_dir: "logs" + data_dir: "data" + +# Server timeouts +server: + timeout_keep_alive: 5 + backlog: 2048 + +# Metadata +meta: + version: "0.1.0" + environment: "dev" \ No newline at end of file diff --git a/00_Globale_Richtlinien/Entworfener_Code/app/config/logging.yaml b/00_Globale_Richtlinien/Entworfener_Code/app/config/logging.yaml new file mode 100644 index 0000000..1e118d5 --- /dev/null +++ b/00_Globale_Richtlinien/Entworfener_Code/app/config/logging.yaml @@ -0,0 +1,57 @@ +version: 1 +disable_existing_loggers: false + +formatters: + standard: + format: "%(asctime)s | %(levelname)s | %(name)s | %(filename)s:%(lineno)d | %(message)s" + datefmt: "%Y-%m-%d %H:%M:%S" + access: + format: '%(asctime)s | %(levelname)s | %(client_addr)s - "%(request_line)s" %(status_code)s' + datefmt: "%Y-%m-%d %H:%M:%S" + +handlers: + console: + class: logging.StreamHandler + level: INFO + formatter: standard + stream: ext://sys.stdout + + app_file: + class: logging.handlers.TimedRotatingFileHandler + level: INFO + formatter: standard + filename: app/logs/app.log + when: D + interval: 1 + backupCount: 7 + encoding: utf-8 + + access_file: + class: logging.handlers.TimedRotatingFileHandler + level: INFO + formatter: access + filename: app/logs/access.log + when: D + interval: 1 + backupCount: 7 + encoding: utf-8 + +loggers: + uvicorn: + level: INFO + handlers: [console, app_file] + propagate: false + + uvicorn.error: + level: INFO + handlers: [console, app_file] + propagate: false + + uvicorn.access: + level: INFO + handlers: [console, access_file] + propagate: false + +root: + level: INFO + handlers: [console, app_file] \ No newline at end of file diff --git a/00_Globale_Richtlinien/Entworfener_Code/app/start.py b/00_Globale_Richtlinien/Entworfener_Code/app/start.py new file mode 100644 index 0000000..312b6fc --- /dev/null +++ b/00_Globale_Richtlinien/Entworfener_Code/app/start.py @@ -0,0 +1,161 @@ +from typing import Any, Dict, Optional, List +import argparse +import logging +import logging.config +import os +from pathlib import Path +import sys + +import uvicorn +import yaml +from fastapi import FastAPI + +# Basisverzeichnis: .../Entworfener_Code/app +BASE_DIR: Path = Path(__file__).resolve().parent +CODE_DIR: Path = BASE_DIR / "code" # .../app/code +CONFIG_DIR: Path = BASE_DIR / "config" # .../app/config + +# Sicherstellen, dass .../app/code importierbar ist (bevorzugt neue Struktur) +if str(CODE_DIR) not in sys.path: + sys.path.insert(0, str(CODE_DIR)) + +# Jetzt Import aus neuer Struktur (app/code/app/main.py) +from app.main import create_app # noqa: E402 + +APP_CONFIG_ENV = "APP_CONFIG_PATH" + + +def load_yaml(path: Path) -> Dict[str, Any]: + """ + Lädt eine YAML-Datei und gibt den Inhalt als Dictionary zurück. + """ + with path.open("r", encoding="utf-8") as f: + return yaml.safe_load(f) or {} + + +def setup_logging(cfg: Dict[str, Any]) -> None: + """ + Initialisiert das Logging anhand der in app/config/logging.yaml definierten Konfiguration. + Stellt sicher, dass das Log-Verzeichnis existiert. + """ + logging_cfg = cfg.get("logging", {}) or {} + paths_cfg = cfg.get("paths", {}) or {} + + log_dir = Path(paths_cfg.get("log_dir", "logs")) + if not log_dir.is_absolute(): + log_dir = BASE_DIR / log_dir + log_dir.mkdir(parents=True, exist_ok=True) + + logging_config_file = logging_cfg.get("config_file", "config/logging.yaml") + logging_path = Path(logging_config_file) + if not logging_path.is_absolute(): + logging_path = BASE_DIR / logging_path + + if logging_path.exists(): + with logging_path.open("r", encoding="utf-8") as f: + config_dict = yaml.safe_load(f) or {} + logging.config.dictConfig(config_dict) + else: + logging.basicConfig( + level=getattr(logging, (logging_cfg.get("level") or "INFO").upper(), logging.INFO), + format="%(asctime)s | %(levelname)s | %(name)s | %(filename)s:%(lineno)d | %(message)s", + ) + + logging.getLogger(__name__).debug("Logging initialisiert. Log-Verzeichnis: %s", str(log_dir)) + + +def load_config_from_env() -> Dict[str, Any]: + """ + Lädt die Anwendungskonfiguration aus der durch APP_CONFIG_PATH angegebenen Datei. + Fällt zurück auf app/config/config.yaml. + """ + env_path = os.environ.get(APP_CONFIG_ENV) + if env_path: + cfg_path = Path(env_path) + else: + cfg_path = CONFIG_DIR / "config.yaml" + + if not cfg_path.exists(): + print(f"Konfigurationsdatei nicht gefunden: {cfg_path}", file=sys.stderr) + return {} + + return load_yaml(cfg_path) + + +def app_factory() -> FastAPI: + """ + Uvicorn-Factory für Reload-Betrieb (importierbare App-Fabrik). + Liest Konfiguration, initialisiert Logging und erzeugt die FastAPI-App. + """ + cfg = load_config_from_env() + setup_logging(cfg) + app = create_app(cfg) + return app + + +def parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace: + """ + CLI-Argumente parsen. + """ + parser = argparse.ArgumentParser(description="Startet den FastAPI-Server (app/code-Struktur).") + parser.add_argument( + "--config", + type=str, + default=str(CONFIG_DIR / "config.yaml"), + help="Pfad zur Konfigurationsdatei (YAML).", + ) + return parser.parse_args(argv) + + +def main(argv: Optional[List[str]] = None) -> None: + """ + Einstiegspunkt: lädt Konfiguration, initialisiert Logging, startet Uvicorn. + """ + args = parse_args(argv) + + # Resolve config path + config_path = Path(args.config) + if not config_path.is_absolute(): + config_path = (BASE_DIR / args.config).resolve() + + if not config_path.exists(): + print(f"Konfigurationsdatei nicht gefunden: {config_path}", file=sys.stderr) + sys.exit(2) + + # Set env var für Factory + os.environ[APP_CONFIG_ENV] = str(config_path) + + cfg = load_yaml(config_path) + setup_logging(cfg) + + app_cfg = cfg.get("app", {}) or {} + host = str(app_cfg.get("host", "0.0.0.0")) + port = int(app_cfg.get("port", 8000)) + reload_enabled = bool(app_cfg.get("reload", False)) + + logger = logging.getLogger("start") + + if reload_enabled: + # Für Reload muss eine importierbare App-Factory übergeben werden + logger.info("Starte Uvicorn mit Reload (Factory-Modus, app/code).") + module_name = Path(__file__).stem # "start" + uvicorn.run( + f"{module_name}:app_factory", + factory=True, + host=host, + port=port, + reload=True, + ) + else: + logger.info("Starte Uvicorn ohne Reload (app/code).") + app = create_app(cfg) + uvicorn.run( + app, + host=host, + port=port, + reload=False, + ) + + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/00_Globale_Richtlinien/Entworfener_Code/requirements.txt b/00_Globale_Richtlinien/Entworfener_Code/requirements.txt new file mode 100644 index 0000000..daaeb63 --- /dev/null +++ b/00_Globale_Richtlinien/Entworfener_Code/requirements.txt @@ -0,0 +1,15 @@ +# Core web framework and server +fastapi>=0.115.0 +uvicorn[standard]>=0.30.0 + +# Configuration +PyYAML>=6.0.2 + +# Testing +pytest>=8.3.1 +httpx>=0.27.2 + +# Optional developer tooling (can be moved to requirements-dev.txt) +mypy>=1.11.2 +ruff>=0.6.4 +black>=24.10.0 \ No newline at end of file diff --git a/00_Globale_Richtlinien/Planung/Code_Style.md b/00_Globale_Richtlinien/Planung/Code_Style.md new file mode 100644 index 0000000..22f16b0 --- /dev/null +++ b/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_.py` +- Testmethoden: `test_` +- 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]* \ No newline at end of file diff --git a/00_Globale_Richtlinien/Planung/Komponenten_Standardstruktur.md b/00_Globale_Richtlinien/Planung/Komponenten_Standardstruktur.md new file mode 100644 index 0000000..f944a83 --- /dev/null +++ b/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 +// +│ +├── 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 +// +│ +├── 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": }` +- `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. \ No newline at end of file diff --git a/00_Globale_Richtlinien/Planung/Namenskonventionen.md b/00_Globale_Richtlinien/Planung/Namenskonventionen.md new file mode 100644 index 0000000..8a68bb8 --- /dev/null +++ b/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_.py` | `test_router.py` | +| Markdown-Dokumente | `PascalCase.md` | `KomponentenStandardstruktur.md` | +| Logdateien | `_.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_` +- 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: `_.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/` | `feature/router-logging` | +| Fix | `fix/` | `fix/memory-leak` | +| Dokumentation | `docs/` | `docs/code-style` | + +Commit-Messages folgen dem Schema: +``` +: + + +``` + +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]* \ No newline at end of file diff --git a/00_Globale_Richtlinien/README.md b/00_Globale_Richtlinien/README.md new file mode 100644 index 0000000..b219542 --- /dev/null +++ b/00_Globale_Richtlinien/README.md @@ -0,0 +1,93 @@ +# 00_Globale_Richtlinien – Gesamtüberblick + +Dieses Verzeichnis bündelt globale Planungsdokumente und einen entworfenen Code-Grundstock, auf dem spätere Komponenten aufbauen. + +## Struktur + +```plaintext +00_Globale_Richtlinien/ +├── Planung/ +│ ├── Komponenten_Standardstruktur.md +│ ├── Code_Style.md +│ └── Namenskonventionen.md +└── Entworfener_Code/ + ├── requirements.txt + ├── Dockerfile + ├── docker-compose.yml + ├── app/ + │ ├── start.py + │ ├── config/ + │ │ ├── config.yaml + │ │ └── logging.yaml + │ └── code/ + │ ├── app/ + │ │ ├── __init__.py + │ │ └── main.py + │ ├── api/ + │ │ ├── __init__.py + │ │ ├── router.py + │ │ └── routes/ + │ │ ├── __init__.py + │ │ └── execute.py + │ ├── core/ + │ │ └── base_component.py + │ ├── src/ + │ │ ├── api.py + │ │ ├── config.py + │ │ ├── logger.py + │ │ └── worker.py + │ └── tests/ + │ └── test_smoke.py +``` + +Hinweise: +- Planung enthält verbindliche Vorgaben zu Struktur, Namens-/Code-Stil und Laufzeitarchitektur. +- Entworfener_Code liefert ein minimales, startfähiges API-Gerüst mit FastAPI, Logging und Tests. + +## Kernfunktionen des Entworfenen Codes + +- Startskript: app/start.py startet den Server, lädt YAML-Konfiguration und Logging. +- FastAPI-App: app/code/app/main.py erzeugt die App, bindet Router und Health-Check. +- Beispiel-API: app/code/api/router.py und app/code/api/routes/execute.py registrieren /api/execute. +- Minimal-API (Gerüst) unter app/code/src/api.py mit: + - POST /start: löst eine nicht-blockierende Start-Routine aus (Delegation an app/code/src/worker.py). + - GET /health: einfacher Health-Check. + - POST /restart und POST /reload: planen (Gerüst) einen Neustart des Prozesses. +- Logging: app/config/logging.yaml (rotierende Logs) und Zugriff über app/code/src/logger.py (Gerüst). +- Tests: app/code/tests/test_smoke.py (pytest). + +## Quickstart lokal (ohne Container) + +Voraussetzungen: Python 3.10+ und pip. + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r 00_Globale_Richtlinien/Entworfener_Code/requirements.txt +python 00_Globale_Richtlinien/Entworfener_Code/app/start.py --config 00_Globale_Richtlinien/Entworfener_Code/app/config/config.yaml +``` + +Swagger: http://localhost:8000/docs + +## Quickstart mit Docker/Compose + +Build & Run: + +```bash +docker build -t entwurf-service 00_Globale_Richtlinien/Entworfener_Code +docker run --rm -p 8000:8000 entwurf-service +# oder: +docker compose -f 00_Globale_Richtlinien/Entworfener_Code/docker-compose.yml up --build +``` + +## Relevante Planungsdokumente + +- Komponenten-Standardstruktur: 00_Globale_Richtlinien/Planung/Komponenten_Standardstruktur.md +- Code Style: 00_Globale_Richtlinien/Planung/Code_Style.md +- Namenskonventionen: 00_Globale_Richtlinien/Planung/Namenskonventionen.md + +## Hinweise zur Weiterentwicklung + +- Die konkrete Neustartstrategie (Supervisor/execv, Backoff, Auth) ist bewusst offen und wird später festgelegt. +- Die Python-Config (app/code/src/config.py) ist die zentrale Quelle; YAML ergänzt externe Konfigurierbarkeit. +- Altstrukturen können in Migrationsschritten bereinigt werden; maßgeblich ist die app/code-Aufteilung. \ No newline at end of file diff --git a/roadmap_readme.md b/roadmap_readme.md new file mode 100644 index 0000000..8461800 --- /dev/null +++ b/roadmap_readme.md @@ -0,0 +1,190 @@ +# 🧭 KI-Cluster Roadmap + +## 🎯 Projektziel +Ein autonomes, modulares KI-Entwicklungscluster für dein Homelab, das in der Lage ist: +- Software eigenständig zu **planen**, **entwickeln**, **testen** und **dokumentieren**, +- mit dir als Benutzer **strategisch zu planen** und **Entscheidungen abzustimmen**, +- **Langzeitwissen** zu speichern und daraus zu lernen, +- und die gesamte Arbeit in **Planung** und **Code** klar zu trennen. + +--- + +## 🗂️ Strukturprinzip + +Jeder Roadmap-Punkt ist ein **eigener Unterordner**, der zwei Hauptbereiche enthält: + +| Ordner | Zweck | +|--------|--------| +| **/Planung** | Enthält alle Konzepte, Architekturideen, Diagramme, Systembeschreibungen und Spezifikationen. | +| **/Entworfener_Code** | Beinhaltet den von der KI erzeugten, getesteten und funktionsfähigen Code, Skripte oder fertige Module. | + +Diese Trennung erlaubt eine saubere Zusammenarbeit zwischen **Strategie- und Builder-Agenten**: +- Die Planung dient als Input für den Builder-Agenten. +- Der fertige Code landet im Unterordner `/Entworfener_Code/`. + +--- + +## 📁 Verzeichnisstruktur + +```plaintext +/KI-Cluster +│ +├── readme.markdown ← Diese Datei (Projektübersicht) +│ +├──/00_Globale_Richtlinien/Entworfener_Code/ +│ │ +│ ├── start.py ← Einstiegspunkt für jede Komponente +│ ├── config.yaml ← Globale Laufzeitkonfiguration (Port, Logging) +│ ├── README.md ← Beschreibung der Basiskomponente +│ │ +│ ├── src/ +│ │ ├── webserver.py ← Einheitlicher HTTP-Server (zeigt README, bietet /api/) +│ │ ├── logmodul.py ← Zentrales Logging-System mit Rotation +│ │ └── placeholder_logic.py ← Beispielhafte Logik als Platzhalter +│ │ +│ └── log/ ← Automatisch angelegte Logdateien (7 Tage / 12 MB Rotation) +│ +├── 01_Zieldefinition_und_Subsysteme/ +│ ├── Planung/ +│ │ ├── Zieldefinition.md +│ │ ├── Systemvision.md +│ │ ├── Subsystem_Uebersicht.md +│ │ └── Agenten_Uebersicht.md +│ ├── Entworfener_Code/ +│ │ └── (spätere Prototypen oder System-Demos) +│ └── README.md +│ +├── 02_API_Design_und_Kommunikation/ +│ ├── Planung/ +│ │ ├── API_Schnittstelle.md +│ │ ├── Kommunikationsprotokolle.md +│ │ └── Nachrichtenformate.md +│ ├── Entworfener_Code/ +│ │ └── (API-Spezifikationen, JSON/YAML-Dateien, Tests) +│ └── README.md +│ +├── 03_Router_und_Orchestrator/ +│ ├── Planung/ +│ │ ├── Router.md +│ │ ├── Routing_Logik.md +│ │ ├── Ereignissteuerung.md +│ │ └── Router_API_Integration.md +│ ├── Entworfener_Code/ +│ │ └── (Router-Implementierungen, Skripte) +│ └── README.md +│ +├── 04_Hauptagenten/ +│ ├── Planung/ +│ │ ├── StrategieAgent.md +│ │ ├── DenkerAgent.md +│ │ ├── BuilderAgent.md +│ │ ├── DiagrammAgent.md +│ │ ├── GedaechtnisAgent.md +│ │ └── Agenten_Logik_Vergleich.md +│ ├── Entworfener_Code/ +│ │ └── (Agenten-Prototypen, Skripte, Konfigurationen) +│ └── README.md +│ +├── 05_Hilfsagenten/ +│ ├── Planung/ +│ │ ├── MemoryManager.md +│ │ ├── WebResearchAgent.md +│ │ ├── EvaluatorAgent.md +│ │ ├── PolicyAgent.md +│ │ └── KommunikationsAgent.md +│ ├── Entworfener_Code/ +│ │ └── (Hilfsagenten-Code, Datenmodule) +│ └── README.md +│ +├── 06_Datenspeicher_und_Gedaechtnis/ +│ ├── Planung/ +│ │ ├── Speicherstruktur.md +│ │ ├── Projektkontext_Index.md +│ │ └── Zugriffssysteme.md +│ ├── Entworfener_Code/ +│ │ └── (z. B. Datenbankadapter, Index-System) +│ └── README.md +│ +├── 07_Workflow_und_Kommunikationsfluss/ +│ ├── Planung/ +│ │ ├── Workflow_Uebersicht.md +│ │ ├── Diagramme.md +│ │ └── Agenten_Fluss.md +│ ├── Entworfener_Code/ +│ │ └── (Eventsteuerung, Workflow-Skripte) +│ └── README.md +│ +├── 08_Builder_Autonomie/ +│ ├── Planung/ +│ │ ├── Builder_Prozess.md +│ │ ├── Testsysteme.md +│ │ ├── Dokumentationspipeline.md +│ │ └── Autonomie_Fluss.md +│ ├── Entworfener_Code/ +│ │ └── (Builder-Agent Code, Testframeworks) +│ └── README.md +│ +├── 09_Dokumentationssystem/ +│ ├── Planung/ +│ │ ├── HowTo_Generator.md +│ │ ├── API_Doku_Generator.md +│ │ └── Strukturkonzept.md +│ ├── Entworfener_Code/ +│ │ └── (Dokumentationsgenerator, Skripte) +│ └── README.md +│ +├── 10_Sicherheit_und_Policy/ +│ ├── Planung/ +│ │ ├── Datenschutz.md +│ │ ├── Compliance.md +│ │ └── Zugriffskontrolle.md +│ ├── Entworfener_Code/ +│ │ └── (Policy-Module, Audit-Systeme) +│ └── README.md +│ +├── 11_Infrastruktur/ +│ ├── Planung/ +│ │ ├── Deployment_Struktur.md +│ │ ├── Container_Setup.md +│ │ ├── Monitoring_System.md +│ │ └── Netzwerkarchitektur.md +│ ├── Entworfener_Code/ +│ │ └── (Dockerfiles, Setup-Skripte) +│ └── README.md +│ +└── 12_Zukunft_und_Erweiterungen/ + ├── Planung/ + │ ├── Neue_Modelle.md + │ ├── CrossCluster_KI.md + │ └── Lernsysteme.md + ├── Entworfener_Code/ + │ └── (Prototypische Erweiterungen) + └── README.md +yaml +Code kopieren + +--- + +## ⚙️ Arbeitsweise + +1. **Planungsphase** + - Hier entsteht das Wissen, die Logik und die Struktur. + - Alles, was gedanklich erarbeitet oder modelliert wird, liegt in `/Planung/`. + +2. **Implementierungsphase (KI-generiert)** + - Der Builder-Agent oder eine andere KI liest aus `/Planung/`. + - Sie erzeugt daraus Code, Tests und Dokumentation → legt alles in `/Entworfener_Code/` ab. + +3. **Validierung & Rückkopplung** + - Wenn der Code funktioniert, kann der Builder-Agent automatisch + Planungsdokumente oder Diagramme in `/Planung/` aktualisieren. + +--- + +## 🔗 Querverweise + +Jeder Unterordner enthält am Ende seiner README: +```markdown +## Verweise +- [⬅ Zurück zur Hauptroadmap](../readme.markdown) +- Nächster Schritt: [Router und Orchestrator](../03_Router_und_Orchestrator/README.md)