madgerm/KI-Cluster-Roadmap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
madgerm
2025-11-12 11:49:38 +01:00
commit 6fddc00ac6
11 changed files with 1567 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
00_Globale_Richtlinien/Entworfener_Code/Dockerfile Normal file
View File

@@ -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"]

59
00_Globale_Richtlinien/Entworfener_Code/app/code/app/main.py Normal file
View File

@@ -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

36
00_Globale_Richtlinien/Entworfener_Code/app/config/config.yaml Normal file
View File

@@ -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"

57
00_Globale_Richtlinien/Entworfener_Code/app/config/logging.yaml Normal file
View File

@@ -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]

161
00_Globale_Richtlinien/Entworfener_Code/app/start.py Normal file
View File

@@ -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()

15
00_Globale_Richtlinien/Entworfener_Code/requirements.txt Normal file
View File

@@ -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

251
00_Globale_Richtlinien/Planung/Code_Style.md Normal file
View File

@@ -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]*

471
00_Globale_Richtlinien/Planung/Komponenten_Standardstruktur.md Normal file
View File

@@ -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.

201
00_Globale_Richtlinien/Planung/Namenskonventionen.md Normal file
View File

@@ -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]*

93
00_Globale_Richtlinien/README.md Normal file
View File

@@ -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.

190
roadmap_readme.md Normal file
View File

@@ -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)