""" FILE: deploy/entrypoint.py DESCRIPTION: Container-Entrypoint für Mindnet (API, UI, Preflight). Prüft vor dem Start alle Annahmen, deren Verletzung still Daten verfälschen oder Inhalte nach außen geben würde, und bricht sonst ab: - Vektor-Dimension und Embedding-Modell (768 / nomic-embed-text) - explizite Umgebung und Collection-Präfix (Dev nie auf Prod-Präfix) - Vault: vorhanden, Sentinel lesbar (NAS gemountet), schreibgeschützt - kein Cloud-LLM-Key ohne ausdrückliche Freigabe - Dienst-URLs gesetzt und nicht auf den Container selbst (localhost) Mit 'preflight --live' zusätzlich (nur lesend): Ollama und Qdrant erreichbar, benötigte Modelle vorhanden, Dimensionen stimmen. VERSION: 1.1.0 STATUS: Active USAGE: entrypoint.py api | ui | preflight [--live] """ from __future__ import annotations import json import os import sys import urllib.error import urllib.parse import urllib.request from pathlib import Path import yaml CLOUD_KEYS = ("OPENROUTER_API_KEY", "GOOGLE_API_KEY") CLOUD_EGRESS_ACK = "MINDNET_ALLOW_CLOUD_EGRESS" SERVICE_URLS = ("MINDNET_OLLAMA_URL", "QDRANT_URL") LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1", "0.0.0.0"} class PreflightError(RuntimeError): pass def _flag(name: str, default: str) -> bool: return os.getenv(name, default).strip().lower() == "true" def check_environment() -> str: env = os.getenv("MINDNET_ENV", "").strip() if env not in {"dev", "prod"}: raise PreflightError("MINDNET_ENV muss 'dev' oder 'prod' sein.") prefix = os.getenv("COLLECTION_PREFIX", "").strip() if not prefix: # Ohne Präfix fällt die App still auf 'mindnet' (= Produktion) zurück. raise PreflightError("COLLECTION_PREFIX muss explizit gesetzt sein.") if env == "dev" and not prefix.endswith("_dev"): raise PreflightError(f"Dev-Umgebung verlangt ein Präfix mit Suffix '_dev' (ist: '{prefix}').") if env == "prod" and prefix.endswith("_dev"): raise PreflightError(f"Prod-Umgebung mit Dev-Präfix '{prefix}'.") return env def _load_profiles(profiles_path: str | None = None) -> dict: # Gleicher Pfad wie in der App (Settings kennt keinen Override dafür). path = Path(profiles_path or "config/llm_profiles.yaml") try: data = yaml.safe_load(path.read_text(encoding="utf-8")) or {} except (OSError, yaml.YAMLError) as e: raise PreflightError(f"LLM-Profile nicht lesbar: {path} ({type(e).__name__}).") from None return data.get("profiles") or {} def check_embeddings(profiles_path: str | None = None) -> None: expected_dim = int(os.getenv("MINDNET_EXPECTED_VECTOR_DIM", "768")) expected_model = os.getenv("MINDNET_EXPECTED_EMBEDDING_MODEL", "nomic-embed-text") # qdrant.py fällt ohne VECTOR_DIM auf 384 (MiniLM) zurück. dim = os.getenv("VECTOR_DIM", "").strip() if dim != str(expected_dim): raise PreflightError(f"VECTOR_DIM muss {expected_dim} sein (ist: '{dim or 'nicht gesetzt'}').") env_model = os.getenv("MINDNET_EMBEDDING_MODEL", "").strip() if env_model and env_model != expected_model: raise PreflightError(f"MINDNET_EMBEDDING_MODEL='{env_model}' weicht von '{expected_model}' ab.") # Das Profil hat Vorrang vor der Umgebung; fehlt es, fällt der Client auf das Chat-Modell zurück. profile = _load_profiles(profiles_path).get("embedding_expert") or {} if profile.get("provider", "ollama") != "ollama" or profile.get("model") != expected_model: raise PreflightError(f"Profil embedding_expert muss ollama/{expected_model} sein.") if int(profile.get("dimensions") or 0) != expected_dim: raise PreflightError(f"Profil embedding_expert muss dimensions={expected_dim} haben.") def check_cloud_egress() -> None: configured = [k for k in CLOUD_KEYS if os.getenv(k, "").strip()] if configured and not _flag(CLOUD_EGRESS_ACK, "false"): # Ohne Privacy Gateway würden Vault-Inhalte unmaskiert an Cloud-Provider gehen. raise PreflightError( f"Cloud-Keys gesetzt ({', '.join(configured)}), aber {CLOUD_EGRESS_ACK}=true fehlt. " "Ohne Privacy Gateway gehen Vault-Inhalte unmaskiert an den Provider." ) def _is_read_only_mount(path: Path) -> bool: if not hasattr(os, "statvfs"): return False # nicht prüfbar -> als beschreibbar behandeln (fail closed) return bool(os.statvfs(path).f_flag & os.ST_RDONLY) def check_vault() -> None: if not _flag("MINDNET_VAULT_REQUIRED", "true"): return root = Path(os.getenv("MINDNET_VAULT_ROOT", "")) if not str(root) or not root.is_dir(): raise PreflightError(f"Vault-Verzeichnis fehlt: '{root}'.") # Ein ausgefallenes NAS hinterlässt einen leeren Mountpunkt; der Sentinel unterscheidet das. sentinel = root / os.getenv("MINDNET_VAULT_SENTINEL", "_system/dictionary/edge_vocabulary.md") try: with sentinel.open("rb") as f: f.read(1) except OSError: raise PreflightError(f"Vault-Sentinel nicht lesbar: '{sentinel}' (NAS nicht gemountet?).") from None if _flag("MINDNET_VAULT_READONLY", "true") and not _is_read_only_mount(root): raise PreflightError(f"Vault '{root}' ist nicht schreibgeschützt gemountet (':ro' erforderlich).") def check_service_urls() -> None: for name in SERVICE_URLS: url = os.getenv(name, "").strip() if not url: # Die App fiele sonst still auf http://127.0.0.1:... zurück, also auf den Container selbst. raise PreflightError(f"{name} muss explizit gesetzt sein.") if urllib.parse.urlsplit(url).hostname in LOOPBACK_HOSTS: raise PreflightError( f"{name}='{url}' zeigt im Container auf den Container selbst. " "Host-Dienste über host.docker.internal ansprechen." ) def _fetch_json(url: str, payload: dict | None = None, headers: dict | None = None, timeout: float = 10): """GET (oder POST mit payload). Netzwerkfehler werden zu PreflightError, HTTPError bleibt erhalten.""" req = urllib.request.Request( url, method="POST" if payload is not None else "GET", data=json.dumps(payload).encode() if payload is not None else None, headers={"Content-Type": "application/json", **(headers or {})}, ) try: with urllib.request.urlopen(req, timeout=timeout) as res: return json.load(res) except urllib.error.HTTPError: raise except (urllib.error.URLError, OSError) as e: hint = "" if urllib.parse.urlsplit(url).hostname == "host.docker.internal": hint = " Lauscht der Dienst auf dem Host nur an 127.0.0.1?" raise PreflightError(f"{url} nicht erreichbar ({getattr(e, 'reason', e)}).{hint}") from None except ValueError: raise PreflightError(f"{url} liefert kein JSON.") from None def required_ollama_models(profiles_path: str | None = None) -> set[str]: models = {p["model"] for p in _load_profiles(profiles_path).values() if isinstance(p, dict) and p.get("provider") == "ollama" and p.get("model")} # Lokales Chat-Modell: Endpunkt der Fallback-Kette ohne Cloud-Keys (Review R4). if os.getenv("MINDNET_LLM_MODEL", "").strip(): models.add(os.environ["MINDNET_LLM_MODEL"].strip()) return models def _has_model(required: str, available: set[str]) -> bool: return required in available or (":" not in required and f"{required}:latest" in available) def check_live(profiles_path: str | None = None) -> None: """Laufzeitprüfung (nur lesend): Erreichbarkeit, Modelle, Embedding- und Collection-Dimension.""" expected_dim = int(os.getenv("MINDNET_EXPECTED_VECTOR_DIM", "768")) ollama = os.getenv("MINDNET_OLLAMA_URL", "").rstrip("/") model = os.getenv("MINDNET_EXPECTED_EMBEDDING_MODEL", "nomic-embed-text") tags = _fetch_json(f"{ollama}/api/tags") available = {m.get("name") for m in tags.get("models") or []} missing = sorted(m for m in required_ollama_models(profiles_path) if not _has_model(m, available)) if missing: raise PreflightError(f"Ollama ({ollama}) fehlen die Modelle: {', '.join(missing)}.") embedding = _fetch_json(f"{ollama}/api/embeddings", {"model": model, "prompt": "preflight"}, timeout=30) got = len(embedding.get("embedding") or []) if got != expected_dim: raise PreflightError(f"Ollama liefert {got} Dimensionen für '{model}', erwartet {expected_dim}.") print(f"preflight: Ollama erreichbar ({ollama}), Modelle vorhanden, '{model}' = {got} Dimensionen.") qdrant = os.getenv("QDRANT_URL", "").rstrip("/") headers = {"api-key": os.environ["QDRANT_API_KEY"]} if os.getenv("QDRANT_API_KEY") else {} try: _fetch_json(f"{qdrant}/collections", headers=headers) except urllib.error.HTTPError as e: raise PreflightError(f"Qdrant ({qdrant}) antwortet mit HTTP {e.code}.") from None prefix = os.getenv("COLLECTION_PREFIX", "") for suffix in ("notes", "chunks"): name = f"{prefix}_{suffix}" try: info = _fetch_json(f"{qdrant}/collections/{name}", headers=headers) except urllib.error.HTTPError as e: if e.code == 404: print(f"preflight: Collection '{name}' existiert noch nicht.") continue raise PreflightError(f"Qdrant-Collection '{name}': HTTP {e.code}.") from None vectors = info["result"]["config"]["params"]["vectors"] sizes = [vectors["size"]] if "size" in vectors else [v["size"] for v in vectors.values()] if any(s != expected_dim for s in sizes): raise PreflightError(f"Collection '{name}' hat Dimension {sizes}, erwartet {expected_dim}.") print(f"preflight: Qdrant erreichbar ({qdrant}), Collections '{prefix}_*' passen.") def run_checks(mode: str) -> None: check_environment() check_embeddings() check_cloud_egress() if mode in {"api", "preflight"}: check_service_urls() check_vault() COMMANDS = { "api": ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"], "ui": ["streamlit", "run", "app/frontend/ui.py", "--server.address", "0.0.0.0", "--server.port", "8501", "--server.headless", "true", "--browser.gatherUsageStats", "false"], } def main(argv: list[str]) -> int: mode = argv[1] if len(argv) > 1 else "api" if mode not in {*COMMANDS, "preflight"}: print(f"Unbekannter Modus '{mode}'. Erlaubt: api, ui, preflight [--live]", file=sys.stderr) return 2 try: run_checks(mode) if mode == "preflight" and "--live" in argv: check_live() except PreflightError as e: print(f"preflight: ABBRUCH: {e}", file=sys.stderr) return 1 if mode == "preflight": print("preflight: OK") return 0 os.execvp(COMMANDS[mode][0], COMMANDS[mode]) return 0 # nicht erreichbar if __name__ == "__main__": sys.exit(main(sys.argv))