Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
347ca50e71 | ||
|
|
6a2ab522fc | ||
|
|
666719ca4c | ||
|
|
6cdad8b046 | ||
|
|
eae30775e3 | ||
|
|
10a3524b59 | ||
|
|
6c15b51e7a | ||
|
|
26fa7732e9 | ||
|
|
5016ed6996 | ||
|
|
c4af7606da | ||
|
|
ded97fc58c | ||
|
|
9d5b52a3c1 | ||
|
|
7f5cdeb4cb | ||
|
|
8f9f83aa79 | ||
|
|
7a225ba2b6 | ||
|
|
0d61a9e191 | ||
|
|
55d1a7e290 | ||
|
|
4537e65428 | ||
|
|
43327c1f6d | ||
|
|
39a6998123 | ||
|
|
273c4c6919 | ||
|
|
2ed4488cf6 | ||
|
|
36490425c5 | ||
|
|
b8cb8bb89b | ||
|
|
6d268d9dfb | ||
|
|
df5f9b3fe4 | ||
|
|
5e67cd470c | ||
|
|
0b2a1f1a63 |
No files matched your search
@@ -0,0 +1,23 @@
|
||||
# Allowlist: Nur was hier ausdrücklich freigegeben ist, gelangt in den Build-Kontext.
|
||||
# Damit landen weder .env-Dateien, Vault-Inhalte, Logs noch lokale venvs im Image.
|
||||
**
|
||||
|
||||
!app/
|
||||
!config/
|
||||
!scripts/
|
||||
!tests/
|
||||
!deploy/
|
||||
# Nur für die statischen Prüfungen in der Test-Stage (nicht im Laufzeit-Image):
|
||||
!.dockerignore
|
||||
!.gitea/workflows/
|
||||
|
||||
# Innerhalb der freigegebenen Ordner wieder ausschließen
|
||||
**/__pycache__/
|
||||
**/*.pyc
|
||||
**/.pytest_cache/
|
||||
config/*.env
|
||||
config/*.local.*
|
||||
config/*_old*
|
||||
config/* - Kopie*
|
||||
deploy/env/*.env
|
||||
tests/temp_*/
|
||||
@@ -0,0 +1,2 @@
|
||||
# Shell-Skripte laufen im Container bzw. auf dem Linux-Runner.
|
||||
*.sh text eol=lf
|
||||
@@ -0,0 +1,53 @@
|
||||
# Mindnet DEV als Container: jeder Push auf develop baut und startet den Dev-Stack
|
||||
# auf dem Runner-Host (Muster wie Kansho). Gleiche Konfiguration wie die systemd-
|
||||
# Dev-Instanz (8002/8502), parallel auf 8012/8512. systemd und Prod bleiben unberührt.
|
||||
# Ablauf und Abbruchbedingungen: deploy/deploy.sh. Prod-Gegenstück (noch inaktiv):
|
||||
# deploy/gitea-workflows/deploy-prod.yml.
|
||||
|
||||
name: Deploy mindnet DEV (Container)
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [develop]
|
||||
workflow_dispatch:
|
||||
|
||||
concurrency:
|
||||
group: deploy-mindnet-dev
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
# Runner auf dem Zielhost (heute llm-node). Bei einem Umzug auf einen anderen
|
||||
# Mini-PC nur das Label und die beiden Pfade anpassen.
|
||||
runs-on: linux_host
|
||||
env:
|
||||
# Unveränderte Konfiguration der systemd-Dev-Instanz.
|
||||
MINDNET_APP_ENV_FILE: /home/llmadmin/mindnet_dev/.env
|
||||
# Nur Container-Angaben (Vorlage: deploy/env/dev.env.example).
|
||||
MINDNET_ENV_FILE: /home/llmadmin/docker/mindnet-dev/container.env
|
||||
steps:
|
||||
# Ohne actions/checkout: kein Abruf von github.com (DNS/Internet auf dem Host
|
||||
# nicht nötig). Holt genau den Commit des Pushes vom eigenen Gitea, mit Job-Token.
|
||||
- name: Checkout
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git init -q .
|
||||
git -c http.extraHeader="Authorization: token ${{ github.token }}" \
|
||||
fetch -q --depth 1 "${{ github.server_url }}/${{ github.repository }}.git" "${{ github.sha }}"
|
||||
git checkout -q --force FETCH_HEAD
|
||||
git clean -q -ffdx
|
||||
git log -1 --format='Checkout %H %s'
|
||||
|
||||
- name: Container-Datei beim ersten Lauf anlegen
|
||||
run: |
|
||||
set -euo pipefail
|
||||
install -d -m 0750 "$(dirname "$MINDNET_ENV_FILE")"
|
||||
if [ ! -f "$MINDNET_ENV_FILE" ]; then
|
||||
install -m 0600 deploy/env/dev.env.example "$MINDNET_ENV_FILE"
|
||||
echo "Container-Datei aus Vorlage angelegt: $MINDNET_ENV_FILE"
|
||||
fi
|
||||
docker version --format 'Docker {{.Server.Version}}'
|
||||
docker compose version
|
||||
|
||||
- name: Test, Build, Preflight, Start, Smoke
|
||||
run: bash deploy/deploy.sh dev
|
||||
+33
-2
@@ -15,13 +15,44 @@ from dotenv import load_dotenv
|
||||
|
||||
# WP-20: Lade Umgebungsvariablen aus der .env Datei
|
||||
# override=True garantiert, dass Änderungen in der .env immer Vorrang haben.
|
||||
load_dotenv(override=True)
|
||||
# WP-24c v4.5.10: Expliziter Pfad für .env-Datei, um Probleme mit Arbeitsverzeichnis zu vermeiden
|
||||
# Suche .env im Projekt-Root (3 Ebenen über app/config.py: app/config.py -> app/ -> root/)
|
||||
_project_root = Path(__file__).parent.parent.parent
|
||||
_env_file = _project_root / ".env"
|
||||
_env_loaded = False
|
||||
|
||||
# Versuche zuerst expliziten Pfad
|
||||
if _env_file.exists():
|
||||
_env_loaded = load_dotenv(_env_file, override=True)
|
||||
if _env_loaded:
|
||||
# Optional: Logging (nur wenn logging bereits initialisiert ist)
|
||||
try:
|
||||
import logging
|
||||
_logger = logging.getLogger(__name__)
|
||||
_logger.debug(f"✅ .env geladen von: {_env_file}")
|
||||
except:
|
||||
pass # Logging noch nicht initialisiert
|
||||
|
||||
# Fallback: Automatische Suche (für Dev/Test oder wenn .env an anderer Stelle liegt)
|
||||
if not _env_loaded:
|
||||
_env_loaded = load_dotenv(override=True)
|
||||
if _env_loaded:
|
||||
try:
|
||||
import logging
|
||||
_logger = logging.getLogger(__name__)
|
||||
_logger.debug(f"✅ .env geladen via automatische Suche (cwd: {Path.cwd()})")
|
||||
except:
|
||||
pass
|
||||
|
||||
class Settings:
|
||||
# --- Qdrant Datenbank ---
|
||||
QDRANT_URL: str = os.getenv("QDRANT_URL", "http://127.0.0.1:6333")
|
||||
QDRANT_API_KEY: str | None = os.getenv("QDRANT_API_KEY")
|
||||
COLLECTION_PREFIX: str = os.getenv("MINDNET_PREFIX", "mindnet_dev")
|
||||
# WP-24c v4.5.10: Harmonisierung - Unterstützt beide Umgebungsvariablen für Abwärtskompatibilität
|
||||
# COLLECTION_PREFIX hat Priorität, MINDNET_PREFIX als Fallback
|
||||
# WP-24c v4.5.10-FIX: Default auf "mindnet" (Prod) statt "mindnet_dev" (Dev)
|
||||
# Dev muss explizit COLLECTION_PREFIX=mindnet_dev in .env setzen
|
||||
COLLECTION_PREFIX: str = os.getenv("COLLECTION_PREFIX") or os.getenv("MINDNET_PREFIX") or "mindnet"
|
||||
|
||||
# WP-22: Vektor-Dimension für das Embedding-Modell (nomic)
|
||||
VECTOR_SIZE: int = int(os.getenv("VECTOR_DIM", "768"))
|
||||
|
||||
@@ -44,7 +44,9 @@ class QdrantConfig:
|
||||
port = os.getenv("QDRANT_PORT")
|
||||
port = int(port) if port else None
|
||||
api_key = os.getenv("QDRANT_API_KEY") or None
|
||||
prefix = os.getenv("COLLECTION_PREFIX") or "mindnet"
|
||||
# WP-24c v4.5.10: Harmonisierung - Unterstützt beide Umgebungsvariablen für Abwärtskompatibilität
|
||||
# COLLECTION_PREFIX hat Priorität, MINDNET_PREFIX als Fallback
|
||||
prefix = os.getenv("COLLECTION_PREFIX") or os.getenv("MINDNET_PREFIX") or "mindnet"
|
||||
dim = int(os.getenv("VECTOR_DIM") or 384)
|
||||
distance = os.getenv("DISTANCE", "Cosine")
|
||||
on_disk_payload = (os.getenv("ON_DISK_PAYLOAD", "true").lower() == "true")
|
||||
|
||||
@@ -910,9 +910,20 @@ def build_edges_for_note(
|
||||
# Schritt 3: ID-Zuweisung nach Scope-Entscheidung
|
||||
final_edges: List[dict] = []
|
||||
|
||||
# WP-24c v4.5.9: Deterministische Sortierung der semantic_groups für konsistente Edge-Extraktion
|
||||
# WP-24c v4.5.10: Deterministische Sortierung der semantic_groups für konsistente Edge-Extraktion
|
||||
# Verhindert Varianz zwischen Batches (33 vs 34 Kanten)
|
||||
sorted_semantic_keys = sorted(semantic_groups.keys())
|
||||
# WICHTIG: target_section kann None sein, daher benötigen wir eine benutzerdefinierte Sortierfunktion
|
||||
def sort_key_func(key_tuple):
|
||||
"""
|
||||
Sortierfunktion für semantic_keys, die None-Werte korrekt behandelt.
|
||||
None wird als leere Zeichenkette behandelt, um Vergleichbarkeit zu gewährleisten.
|
||||
"""
|
||||
kind, semantic_source, target_id, target_section = key_tuple
|
||||
# Konvertiere None zu leerem String für konsistente Sortierung
|
||||
target_section_safe = target_section if target_section is not None else ""
|
||||
return (kind, semantic_source, target_id, target_section_safe)
|
||||
|
||||
sorted_semantic_keys = sorted(semantic_groups.keys(), key=sort_key_func)
|
||||
|
||||
for semantic_key in sorted_semantic_keys:
|
||||
group = semantic_groups[semantic_key]
|
||||
|
||||
@@ -216,6 +216,9 @@ def _build_explanation(
|
||||
|
||||
direction = "in" if tgt == target_note_id else "out"
|
||||
|
||||
# WP-24c v4.5.10: Robuste EdgeDTO-Erstellung mit Fehlerbehandlung
|
||||
# Falls Provenance-Wert nicht unterstützt wird, verwende Fallback
|
||||
try:
|
||||
edge_obj = EdgeDTO(
|
||||
id=f"{src}->{tgt}:{kind}",
|
||||
kind=kind,
|
||||
@@ -227,6 +230,28 @@ def _build_explanation(
|
||||
confidence=conf
|
||||
)
|
||||
edges_dto.append(edge_obj)
|
||||
except Exception as e:
|
||||
# WP-24c v4.5.10: Fallback bei Validierungsfehler (z.B. alte EdgeDTO-Version im Cache)
|
||||
logger.warning(
|
||||
f"⚠️ [EDGE-DTO] Provenance '{prov}' nicht unterstützt für Edge {src}->{tgt} ({kind}). "
|
||||
f"Fehler: {e}. Verwende Fallback 'explicit'."
|
||||
)
|
||||
# Fallback: Verwende 'explicit' als sicheren Default
|
||||
try:
|
||||
edge_obj = EdgeDTO(
|
||||
id=f"{src}->{tgt}:{kind}",
|
||||
kind=kind,
|
||||
source=src,
|
||||
target=tgt,
|
||||
weight=conf,
|
||||
direction=direction,
|
||||
provenance="explicit", # Fallback
|
||||
confidence=conf
|
||||
)
|
||||
edges_dto.append(edge_obj)
|
||||
except Exception as e2:
|
||||
logger.error(f"❌ [EDGE-DTO] Auch Fallback fehlgeschlagen: {e2}. Überspringe Edge.")
|
||||
# Überspringe diese Kante - besser als kompletter Fehler
|
||||
|
||||
# Die 3 wichtigsten Kanten als Begründung formulieren
|
||||
top_edges = sorted(edges_dto, key=lambda e: e.confidence, reverse=True)
|
||||
|
||||
+12
-1
@@ -109,12 +109,23 @@ def create_app() -> FastAPI:
|
||||
@app.get("/healthz")
|
||||
def healthz():
|
||||
"""Bietet Statusinformationen über die Engine und Datenbank-Verbindung."""
|
||||
# WP-24c v4.5.10: Prüfe EdgeDTO-Version zur Laufzeit
|
||||
edge_dto_supports_callout = False
|
||||
try:
|
||||
from app.models.dto import EdgeDTO
|
||||
import inspect
|
||||
source = inspect.getsource(EdgeDTO)
|
||||
edge_dto_supports_callout = "explicit:callout" in source
|
||||
except Exception:
|
||||
pass # Fehler beim Prüfen ist nicht kritisch
|
||||
|
||||
return {
|
||||
"status": "ok",
|
||||
"version": "1.1.0",
|
||||
"qdrant": s.QDRANT_URL,
|
||||
"prefix": s.COLLECTION_PREFIX,
|
||||
"moe_enabled": True
|
||||
"moe_enabled": True,
|
||||
"edge_dto_supports_callout": edge_dto_supports_callout # WP-24c v4.5.10: Diagnose-Hilfe
|
||||
}
|
||||
|
||||
# Inkludieren der Router (100% Kompatibilität erhalten)
|
||||
|
||||
@@ -32,9 +32,14 @@ streams_library:
|
||||
top_k: 5
|
||||
edge_boosts:
|
||||
guides: 3.0
|
||||
enforced_by: 2.5
|
||||
depends_on: 2.5
|
||||
based_on: 2.0
|
||||
|
||||
upholds: 2.5
|
||||
violates: 2.5
|
||||
aligned_with: 2.0
|
||||
conflicts_with: 2.0
|
||||
supports: 1.5
|
||||
contradicts: 1.5
|
||||
facts_stream:
|
||||
name: "Operative Realität"
|
||||
llm_profile: "synthesis_pro"
|
||||
@@ -60,6 +65,8 @@ streams_library:
|
||||
related_to: 1.5
|
||||
experienced_in: 2.0
|
||||
expert_for: 2.5
|
||||
followed_by: 2.0
|
||||
preceded_by: 2.0
|
||||
|
||||
risk_stream:
|
||||
name: "Risiko-Radar"
|
||||
|
||||
+26
-17
@@ -94,7 +94,7 @@ llm_settings:
|
||||
types:
|
||||
|
||||
experience:
|
||||
chunking_profile: sliding_smart_edges
|
||||
chunking_profile: structured_smart_edges
|
||||
retriever_weight: 1.10
|
||||
detection_keywords: ["erleben", "reagieren", "handeln", "prägen", "reflektieren"]
|
||||
schema:
|
||||
@@ -104,7 +104,7 @@ types:
|
||||
- "Reflexion & Learning (Was lerne ich daraus?)"
|
||||
|
||||
insight:
|
||||
chunking_profile: sliding_smart_edges
|
||||
chunking_profile: structured_smart_edges
|
||||
retriever_weight: 1.20
|
||||
detection_keywords: ["beobachten", "erkennen", "verstehen", "analysieren", "schlussfolgern"]
|
||||
schema:
|
||||
@@ -114,7 +114,7 @@ types:
|
||||
- "Handlungsempfehlung"
|
||||
|
||||
project:
|
||||
chunking_profile: sliding_smart_edges
|
||||
chunking_profile: structured_smart_edges
|
||||
retriever_weight: 0.97
|
||||
detection_keywords: ["umsetzen", "planen", "starten", "bauen", "abschließen"]
|
||||
schema:
|
||||
@@ -214,7 +214,7 @@ types:
|
||||
- "Strategie"
|
||||
|
||||
need:
|
||||
chunking_profile: sliding_smart_edges
|
||||
chunking_profile: structured_smart_edges
|
||||
retriever_weight: 1.05
|
||||
detection_keywords: ["bedürfnis", "brauchen", "mangel", "erfüllung"]
|
||||
schema:
|
||||
@@ -223,7 +223,7 @@ types:
|
||||
- "Bezug zu Werten"
|
||||
|
||||
motivation:
|
||||
chunking_profile: sliding_smart_edges
|
||||
chunking_profile: structured_smart_edges
|
||||
retriever_weight: 0.95
|
||||
detection_keywords: ["motivation", "antrieb", "warum", "energie"]
|
||||
schema:
|
||||
@@ -244,14 +244,15 @@ types:
|
||||
schema: ["Aktueller Zustand", "Auslöser", "Auswirkung auf den Tag"]
|
||||
|
||||
boundary:
|
||||
chunking_profile: sliding_smart_edges
|
||||
chunking_profile: structured_smart_edges
|
||||
retriever_weight: 0.90
|
||||
detection_keywords: ["grenze", "nein sagen", "limit", "schutz"]
|
||||
schema: ["Die Grenze", "Warum sie wichtig ist", "Konsequenz bei Verletzung"]
|
||||
|
||||
goal:
|
||||
chunking_profile: sliding_smart_edges
|
||||
chunking_profile: structured_smart_edges
|
||||
retriever_weight: 0.95
|
||||
detection_keywords: ["ziel", "zielzustand", "kpi", "zeitrahmen", "deadline", "meilenstein"]
|
||||
schema: ["Zielzustand", "Zeitrahmen & KPIs", "Motivation"]
|
||||
|
||||
risk:
|
||||
@@ -261,41 +262,49 @@ types:
|
||||
schema: ["Beschreibung des Risikos", "Auswirkungen", "Gegenmaßnahmen"]
|
||||
|
||||
concept:
|
||||
chunking_profile: sliding_smart_edges
|
||||
retriever_weight: 0.60
|
||||
chunking_profile: structured_smart_edges
|
||||
retriever_weight: 0.6
|
||||
detection_keywords: ["definition", "konzept", "begriff", "modell", "rahmen", "theorie"]
|
||||
schema: ["Definition", "Kontext", "Verwandte Konzepte"]
|
||||
|
||||
task:
|
||||
chunking_profile: sliding_short
|
||||
retriever_weight: 0.80
|
||||
retriever_weight: 0.8
|
||||
detection_keywords: ["aufgabe", "todo", "next_action", "erledigen", "definition_of_done", "checkliste"]
|
||||
schema: ["Aufgabe", "Kontext", "Definition of Done"]
|
||||
|
||||
journal:
|
||||
chunking_profile: sliding_standard
|
||||
retriever_weight: 0.80
|
||||
retriever_weight: 0.8
|
||||
detection_keywords: ["journal", "tagebuch", "log", "eintrag", "reflexion", "heute"]
|
||||
schema: ["Log-Eintrag", "Gedanken"]
|
||||
|
||||
source:
|
||||
chunking_profile: sliding_standard
|
||||
retriever_weight: 0.50
|
||||
retriever_weight: 0.5
|
||||
detection_keywords: ["quelle", "paper", "buch", "artikel", "link", "zitat", "studie"]
|
||||
schema: ["Metadaten", "Zusammenfassung", "Zitate"]
|
||||
|
||||
glossary:
|
||||
chunking_profile: sliding_short
|
||||
retriever_weight: 0.40
|
||||
retriever_weight: 0.4
|
||||
detection_keywords: ["glossar", "begriff", "definition", "terminologie"]
|
||||
schema: ["Begriff", "Definition"]
|
||||
|
||||
person:
|
||||
chunking_profile: sliding_standard
|
||||
retriever_weight: 0.50
|
||||
schema: ["Rolle", "Beziehung", "Kontext"]
|
||||
retriever_weight: 0.5
|
||||
detection_keywords: ["person", "mensch", "kontakt", "name", "beziehung", "stakeholder"]
|
||||
schema: ["Profile", "Beziehung", "Kontext"]
|
||||
|
||||
event:
|
||||
chunking_profile: sliding_standard
|
||||
retriever_weight: 0.60
|
||||
retriever_weight: 0.6
|
||||
detection_keywords: ["ereignis", "termin", "datum", "ort", "teilnehmer", "meeting"]
|
||||
schema: ["Datum & Ort", "Teilnehmer", "Ergebnisse"]
|
||||
|
||||
default:
|
||||
chunking_profile: sliding_standard
|
||||
retriever_weight: 1.00
|
||||
retriever_weight: 1.0
|
||||
detection_keywords: []
|
||||
schema: ["Inhalt"]
|
||||
@@ -0,0 +1 @@
|
||||
[0114/152756.633:ERROR:third_party\crashpad\crashpad\util\win\registration_protocol_win.cc:108] CreateFile: Das System kann die angegebene Datei nicht finden. (0x2)
|
||||
@@ -0,0 +1 @@
|
||||
__pycache__/
|
||||
@@ -0,0 +1,66 @@
|
||||
# syntax=docker/dockerfile:1.7
|
||||
#
|
||||
# Mindnet-Image für API und Streamlit-UI (ein Image, Modus per CMD: api | ui | preflight).
|
||||
# Build-Kontext ist das Repository-Root; die Allowlist steht in /.dockerignore.
|
||||
#
|
||||
# docker build -f deploy/Dockerfile -t mindnet:<git-sha> .
|
||||
#
|
||||
# Reproduzierbarkeit: Basis-Image per Digest, Abhängigkeiten per Hash-Lock
|
||||
# (deploy/requirements.lock). Kein torch / sentence-transformers: Embeddings
|
||||
# kommen ausschließlich von Ollama (nomic-embed-text, 768 Dimensionen).
|
||||
|
||||
ARG PYTHON_IMAGE=python:3.12-slim-bookworm@sha256:e697c81897302a4c4333bade000d98038fbb21eb064f8ee1fd42d02ebcd9d337
|
||||
|
||||
# --- Abhängigkeiten in ein isoliertes venv -----------------------------------
|
||||
FROM ${PYTHON_IMAGE} AS deps
|
||||
ENV PIP_NO_CACHE_DIR=1 \
|
||||
PIP_DISABLE_PIP_VERSION_CHECK=1 \
|
||||
PYTHONDONTWRITEBYTECODE=1
|
||||
COPY deploy/requirements.lock /tmp/requirements.lock
|
||||
RUN python -m venv /opt/venv \
|
||||
&& /opt/venv/bin/pip install --require-hashes --no-deps -r /tmp/requirements.lock
|
||||
|
||||
# --- Laufzeit-Image -------------------------------------------------------------
|
||||
FROM ${PYTHON_IMAGE} AS runtime
|
||||
ARG MINDNET_UID=10001
|
||||
ENV PATH=/opt/venv/bin:${PATH} \
|
||||
PYTHONDONTWRITEBYTECODE=1 \
|
||||
PYTHONUNBUFFERED=1 \
|
||||
PYTHONPATH=/app \
|
||||
HOME=/tmp \
|
||||
STREAMLIT_BROWSER_GATHER_USAGE_STATS=false
|
||||
|
||||
RUN groupadd --system --gid ${MINDNET_UID} mindnet \
|
||||
&& useradd --system --uid ${MINDNET_UID} --gid mindnet --no-create-home --shell /usr/sbin/nologin mindnet
|
||||
|
||||
COPY --from=deps /opt/venv /opt/venv
|
||||
|
||||
WORKDIR /app
|
||||
# Code und Konfiguration gehören root und sind für den Laufzeitnutzer nur lesbar.
|
||||
COPY app/ app/
|
||||
COPY config/ config/
|
||||
COPY scripts/ scripts/
|
||||
COPY deploy/entrypoint.py deploy/healthcheck.py /opt/mindnet/
|
||||
|
||||
# Einzige beschreibbare Pfade (als Volumes gemountet): Logs und Laufzeitdaten.
|
||||
RUN install -d -o mindnet -g mindnet -m 0750 /app/logs /app/data /app/data/logs
|
||||
|
||||
USER mindnet:mindnet
|
||||
EXPOSE 8000 8501
|
||||
ENTRYPOINT ["python", "/opt/mindnet/entrypoint.py"]
|
||||
CMD ["api"]
|
||||
|
||||
# --- Test-Image (nur für nichtproduktive Läufe) ---------------------------------
|
||||
FROM runtime AS test
|
||||
USER root
|
||||
COPY deploy/requirements-test.lock /tmp/requirements-test.lock
|
||||
RUN pip install --no-cache-dir --require-hashes --no-deps -r /tmp/requirements-test.lock
|
||||
COPY tests/ tests/
|
||||
COPY deploy/ deploy/
|
||||
COPY .dockerignore ./
|
||||
COPY .gitea/workflows/ .gitea/workflows/
|
||||
USER mindnet:mindnet
|
||||
ENTRYPOINT []
|
||||
CMD ["python", "-m", "pytest", "-q", "-p", "no:cacheprovider", \
|
||||
"tests/test_container_preflight.py", "tests/test_container_connectivity.py", \
|
||||
"tests/test_container_appenv.py"]
|
||||
@@ -0,0 +1,96 @@
|
||||
"""
|
||||
FILE: deploy/appenv.py
|
||||
DESCRIPTION: Liest die unveränderte .env der systemd-Instanz und leitet daraus ab, was
|
||||
Compose für denselben Betrieb im Container braucht:
|
||||
- Vault: Host-Pfad und Einhängepunkt so, dass MINDNET_VAULT_ROOT der .env im
|
||||
Container auf dasselbe Verzeichnis zeigt (relativ -> unter /app, wie unter
|
||||
dem WorkingDirectory der systemd-Unit)
|
||||
- erwartetes Collection-Präfix für den Smoke-Test
|
||||
Prüft außerdem, dass die Container-Datei nur Container-Angaben enthält und
|
||||
damit keine Anwendungskonfiguration überschreibt.
|
||||
Nur Standardbibliothek (läuft direkt auf dem Runner).
|
||||
VERSION: 1.0.0
|
||||
STATUS: Active
|
||||
USAGE: appenv.py <systemd.env> <container.env> -> Shell-Zuweisungen auf stdout
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import posixpath
|
||||
import shlex
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
# Einzige Schlüssel, die die Container-Datei setzen darf.
|
||||
CONTAINER_KEYS = {
|
||||
"MINDNET_API_PORT", "MINDNET_API_BIND", "MINDNET_UI_PORT", "MINDNET_UI_BIND",
|
||||
"MINDNET_API_MEM_LIMIT", "MINDNET_UI_MEM_LIMIT", "MINDNET_ALLOW_CLOUD_EGRESS",
|
||||
"MINDNET_VAULT_SENTINEL",
|
||||
}
|
||||
APP_WORKDIR = "/app"
|
||||
DEFAULT_VAULT_ROOT = "./vault_master" # Default aus app/config.py
|
||||
DEFAULT_PREFIX = "mindnet" # Default aus app/config.py
|
||||
|
||||
|
||||
class AppEnvError(RuntimeError):
|
||||
pass
|
||||
|
||||
|
||||
def parse(path: str) -> dict[str, str]:
|
||||
"""Einfacher dotenv-Parser (KEY=VALUE, optional 'export', Quotes, Kommentare)."""
|
||||
values = {}
|
||||
for raw in Path(path).read_text(encoding="utf-8").splitlines():
|
||||
line = raw.strip()
|
||||
if not line or line.startswith("#") or "=" not in line:
|
||||
continue
|
||||
if line.startswith("export "):
|
||||
line = line[len("export "):].lstrip()
|
||||
key, value = (part.strip() for part in line.split("=", 1))
|
||||
if len(value) >= 2 and value[0] in "\"'" and value[-1] == value[0]:
|
||||
value = value[1:-1]
|
||||
elif " #" in value:
|
||||
value = value.split(" #", 1)[0].rstrip()
|
||||
values[key] = value
|
||||
return values
|
||||
|
||||
|
||||
def vault_mount(app_env_path: str, values: dict[str, str]) -> tuple[str, str]:
|
||||
root = values.get("MINDNET_VAULT_ROOT") or DEFAULT_VAULT_ROOT
|
||||
if posixpath.isabs(root):
|
||||
return posixpath.normpath(root), posixpath.normpath(root)
|
||||
# systemd startet im Ordner der .env (WorkingDirectory), der Container in /app.
|
||||
host_dir = posixpath.dirname(Path(app_env_path).as_posix())
|
||||
return posixpath.normpath(posixpath.join(host_dir, root)), posixpath.normpath(posixpath.join(APP_WORKDIR, root))
|
||||
|
||||
|
||||
def derive(app_env_path: str, container_env_path: str) -> dict[str, str]:
|
||||
extra = sorted(set(parse(container_env_path)) - CONTAINER_KEYS)
|
||||
if extra:
|
||||
raise AppEnvError(
|
||||
f"{container_env_path} darf nur Container-Angaben enthalten; "
|
||||
f"Anwendungswerte gehören in {app_env_path}: {', '.join(extra)}"
|
||||
)
|
||||
values = parse(app_env_path)
|
||||
host, target = vault_mount(app_env_path, values)
|
||||
return {
|
||||
"MINDNET_VAULT_HOST_PATH": host,
|
||||
"MINDNET_VAULT_TARGET": target,
|
||||
"MINDNET_EXPECTED_PREFIX": values.get("COLLECTION_PREFIX") or DEFAULT_PREFIX,
|
||||
}
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
if len(argv) != 3:
|
||||
print("Aufruf: appenv.py <systemd.env> <container.env>", file=sys.stderr)
|
||||
return 2
|
||||
try:
|
||||
derived = derive(argv[1], argv[2])
|
||||
except (OSError, AppEnvError) as e:
|
||||
print(f"appenv: {e}", file=sys.stderr)
|
||||
return 1
|
||||
for key, value in derived.items():
|
||||
print(f"{key}={shlex.quote(value)}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv))
|
||||
@@ -0,0 +1,98 @@
|
||||
# Mindnet ENTWICKLUNG als Container: dieselbe Anwendung mit derselben Konfiguration
|
||||
# wie die systemd-Dev-Instanz (8002/8502), parallel auf 8012/8512 zum Vergleich.
|
||||
#
|
||||
# Gestartet über deploy/deploy.sh dev. Zwei Dateien, beide nur auf dem Host:
|
||||
# - MINDNET_APP_ENV_FILE: die unveränderte .env der systemd-Dev-Instanz
|
||||
# - MINDNET_ENV_FILE: nur Container-Angaben (Ports, Bind-Adressen, Freigaben)
|
||||
# Fest überschrieben wird nur, was im Container anders lauten muss: die Adressen
|
||||
# der Host-Dienste (statt 127.0.0.1). Vault-Pfad und Präfix kommen aus der .env.
|
||||
|
||||
name: mindnet-dev
|
||||
|
||||
x-hardening: &hardening
|
||||
image: mindnet:${MINDNET_IMAGE_TAG:-dev}
|
||||
build:
|
||||
context: ..
|
||||
dockerfile: deploy/Dockerfile
|
||||
target: runtime
|
||||
env_file:
|
||||
- ${MINDNET_APP_ENV_FILE:?MINDNET_APP_ENV_FILE auf die .env der systemd-Dev-Instanz setzen}
|
||||
- ${MINDNET_ENV_FILE:-env/dev.env}
|
||||
read_only: true
|
||||
tmpfs: ["/tmp:size=64m,mode=1777"]
|
||||
cap_drop: [ALL]
|
||||
security_opt: ["no-new-privileges:true"]
|
||||
init: true
|
||||
pids_limit: 256
|
||||
restart: unless-stopped
|
||||
extra_hosts: ["host.docker.internal:host-gateway"]
|
||||
logging:
|
||||
driver: json-file
|
||||
options: {max-size: "10m", max-file: "3"}
|
||||
networks: [mindnet-dev]
|
||||
|
||||
# Container-bedingte Werte; haben Vorrang vor beiden env-Dateien.
|
||||
x-container-env: &container-env
|
||||
MINDNET_ENV: dev
|
||||
QDRANT_URL: http://host.docker.internal:6333
|
||||
MINDNET_OLLAMA_URL: http://host.docker.internal:11434
|
||||
VECTOR_DIM: "768"
|
||||
MINDNET_EXPECTED_VECTOR_DIM: "768"
|
||||
MINDNET_EXPECTED_EMBEDDING_MODEL: nomic-embed-text
|
||||
MINDNET_VAULT_READONLY: "true"
|
||||
|
||||
services:
|
||||
api:
|
||||
<<: *hardening
|
||||
command: ["api"]
|
||||
environment:
|
||||
<<: *container-env
|
||||
volumes:
|
||||
# Derselbe Vault wie systemd-Dev, eingehängt dort, wo MINDNET_VAULT_ROOT hinzeigt.
|
||||
# Nur lesend, solange beide Instanzen parallel laufen.
|
||||
- type: bind
|
||||
source: ${MINDNET_VAULT_HOST_PATH:?wird von deploy/deploy.sh aus der .env abgeleitet}
|
||||
target: ${MINDNET_VAULT_TARGET:?wird von deploy/deploy.sh aus der .env abgeleitet}
|
||||
read_only: true
|
||||
bind:
|
||||
create_host_path: false
|
||||
propagation: rslave
|
||||
- logs:/app/logs
|
||||
- data:/app/data
|
||||
ports: ["${MINDNET_API_BIND:-127.0.0.1}:${MINDNET_API_PORT:-8012}:8000"]
|
||||
mem_limit: ${MINDNET_API_MEM_LIMIT:-2g}
|
||||
healthcheck:
|
||||
test: ["CMD", "python", "/opt/mindnet/healthcheck.py", "api"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 40s
|
||||
|
||||
ui:
|
||||
<<: *hardening
|
||||
command: ["ui"]
|
||||
environment:
|
||||
<<: *container-env
|
||||
MINDNET_VAULT_REQUIRED: "false"
|
||||
MINDNET_API_URL: http://api:8000
|
||||
volumes:
|
||||
- data:/app/data:ro
|
||||
# Wie systemd (STREAMLIT_SERVER_ADDRESS=0.0.0.0): im LAN erreichbar.
|
||||
ports: ["${MINDNET_UI_BIND:-0.0.0.0}:${MINDNET_UI_PORT:-8512}:8501"]
|
||||
mem_limit: ${MINDNET_UI_MEM_LIMIT:-1g}
|
||||
depends_on:
|
||||
api: {condition: service_healthy}
|
||||
healthcheck:
|
||||
test: ["CMD", "python", "/opt/mindnet/healthcheck.py", "ui"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 30s
|
||||
|
||||
volumes:
|
||||
logs:
|
||||
data:
|
||||
|
||||
networks:
|
||||
mindnet-dev:
|
||||
driver: bridge
|
||||
@@ -0,0 +1,100 @@
|
||||
# Mindnet PRODUKTION als Container (Vorlage, noch NICHT aktiv): dieselbe Anwendung
|
||||
# mit derselben Konfiguration wie die systemd-Prod-Instanz (8001/8501), parallel auf
|
||||
# 8011/8511 zum Vergleich. Umschaltung erst mit Freigabe (Gate G5).
|
||||
#
|
||||
# Gestartet über deploy/deploy.sh prod. Zwei Dateien, beide nur auf dem Host:
|
||||
# - MINDNET_APP_ENV_FILE: die unveränderte .env der systemd-Prod-Instanz
|
||||
# - MINDNET_ENV_FILE: nur Container-Angaben (Ports, Bind-Adressen, Freigaben)
|
||||
# Fest überschrieben wird nur, was im Container anders lauten muss: die Adressen
|
||||
# der Host-Dienste (statt 127.0.0.1). Vault-Pfad und Präfix kommen aus der .env.
|
||||
# Vault nur lesend, bis R2 (Pfadsicherheit beim Speichern) behoben ist.
|
||||
|
||||
name: mindnet-prod
|
||||
|
||||
x-hardening: &hardening
|
||||
image: mindnet:${MINDNET_IMAGE_TAG:?MINDNET_IMAGE_TAG setzen (z. B. prod-<commit>)}
|
||||
build:
|
||||
context: ..
|
||||
dockerfile: deploy/Dockerfile
|
||||
target: runtime
|
||||
env_file:
|
||||
- ${MINDNET_APP_ENV_FILE:?MINDNET_APP_ENV_FILE auf die .env der systemd-Prod-Instanz setzen}
|
||||
- ${MINDNET_ENV_FILE:-env/prod.env}
|
||||
read_only: true
|
||||
tmpfs: ["/tmp:size=64m,mode=1777"]
|
||||
cap_drop: [ALL]
|
||||
security_opt: ["no-new-privileges:true"]
|
||||
init: true
|
||||
pids_limit: 256
|
||||
restart: unless-stopped
|
||||
extra_hosts: ["host.docker.internal:host-gateway"]
|
||||
logging:
|
||||
driver: json-file
|
||||
options: {max-size: "10m", max-file: "3"}
|
||||
networks: [mindnet-prod]
|
||||
|
||||
# Container-bedingte Werte; haben Vorrang vor beiden env-Dateien.
|
||||
x-container-env: &container-env
|
||||
MINDNET_ENV: prod
|
||||
QDRANT_URL: http://host.docker.internal:6333
|
||||
MINDNET_OLLAMA_URL: http://host.docker.internal:11434
|
||||
VECTOR_DIM: "768"
|
||||
MINDNET_EXPECTED_VECTOR_DIM: "768"
|
||||
MINDNET_EXPECTED_EMBEDDING_MODEL: nomic-embed-text
|
||||
MINDNET_VAULT_READONLY: "true"
|
||||
|
||||
services:
|
||||
api:
|
||||
<<: *hardening
|
||||
command: ["api"]
|
||||
environment:
|
||||
<<: *container-env
|
||||
volumes:
|
||||
# Derselbe Vault wie systemd-Prod, eingehängt dort, wo MINDNET_VAULT_ROOT hinzeigt.
|
||||
# Nur lesend, solange beide Instanzen parallel laufen.
|
||||
- type: bind
|
||||
source: ${MINDNET_VAULT_HOST_PATH:?wird von deploy/deploy.sh aus der .env abgeleitet}
|
||||
target: ${MINDNET_VAULT_TARGET:?wird von deploy/deploy.sh aus der .env abgeleitet}
|
||||
read_only: true
|
||||
bind:
|
||||
create_host_path: false
|
||||
propagation: rslave
|
||||
- logs:/app/logs
|
||||
- data:/app/data
|
||||
ports: ["${MINDNET_API_BIND:-127.0.0.1}:${MINDNET_API_PORT:-8011}:8000"]
|
||||
mem_limit: ${MINDNET_API_MEM_LIMIT:-2g}
|
||||
healthcheck:
|
||||
test: ["CMD", "python", "/opt/mindnet/healthcheck.py", "api"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 40s
|
||||
|
||||
ui:
|
||||
<<: *hardening
|
||||
command: ["ui"]
|
||||
environment:
|
||||
<<: *container-env
|
||||
MINDNET_VAULT_REQUIRED: "false"
|
||||
MINDNET_API_URL: http://api:8000
|
||||
volumes:
|
||||
- data:/app/data:ro
|
||||
# Wie systemd (STREAMLIT_SERVER_ADDRESS=0.0.0.0): im LAN erreichbar.
|
||||
ports: ["${MINDNET_UI_BIND:-0.0.0.0}:${MINDNET_UI_PORT:-8511}:8501"]
|
||||
mem_limit: ${MINDNET_UI_MEM_LIMIT:-1g}
|
||||
depends_on:
|
||||
api: {condition: service_healthy}
|
||||
healthcheck:
|
||||
test: ["CMD", "python", "/opt/mindnet/healthcheck.py", "ui"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 30s
|
||||
|
||||
volumes:
|
||||
logs:
|
||||
data:
|
||||
|
||||
networks:
|
||||
mindnet-prod:
|
||||
driver: bridge
|
||||
Executable
+92
@@ -0,0 +1,92 @@
|
||||
#!/usr/bin/env bash
|
||||
# Baut, prüft und startet einen Mindnet-Container-Stack. Genutzt von den
|
||||
# Gitea-Workflows (develop -> dev, main -> prod) und für manuelle Deploys.
|
||||
#
|
||||
# MINDNET_APP_ENV_FILE=/home/llmadmin/mindnet_dev/.env # MINDNET_ENV_FILE=/home/llmadmin/docker/mindnet-dev/container.env deploy/deploy.sh dev
|
||||
#
|
||||
# MINDNET_APP_ENV_FILE ist die unveränderte .env der systemd-Instanz (gleiche Konfiguration),
|
||||
# MINDNET_ENV_FILE enthält nur Container-Angaben (deploy/env/<env>.env.example).
|
||||
#
|
||||
# Ablauf (jeder Schritt bricht ab, bevor der laufende Stack angefasst wird):
|
||||
# 1. Container-Tests im Test-Image, ohne Netzwerk (blockierend)
|
||||
# 2. volle Testsuite ohne Netzwerk (informativ, bekannte Fehler siehe Migrationsplan)
|
||||
# 3. Image bauen, Tag = Umgebung + Commit
|
||||
# 4. preflight --live: Ollama/Qdrant erreichbar, Modelle, 768 Dimensionen, Vault (nur lesend)
|
||||
# 5. up --wait (Healthchecks), danach smoke.py über die veröffentlichten Ports
|
||||
# 6. Prod: bei Fehler Rückkehr zum letzten erfolgreichen Tag
|
||||
#
|
||||
# Beide Dateien liegen auf dem Host außerhalb von Git; im Verzeichnis der Container-Datei
|
||||
# merkt sich das Skript den letzten erfolgreichen Image-Tag (last_good_tag).
|
||||
set -euo pipefail
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
ENV="${1:-}"
|
||||
case "$ENV" in
|
||||
dev|prod) ;;
|
||||
*) echo "Aufruf: deploy/deploy.sh dev|prod" >&2; exit 2 ;;
|
||||
esac
|
||||
: "${MINDNET_APP_ENV_FILE:?MINDNET_APP_ENV_FILE auf die .env der systemd-Instanz setzen}"
|
||||
: "${MINDNET_ENV_FILE:?MINDNET_ENV_FILE auf die Container-Datei des Hosts setzen}"
|
||||
for f in "$MINDNET_APP_ENV_FILE" "$MINDNET_ENV_FILE"; do
|
||||
[ -f "$f" ] || { echo "env-Datei fehlt: $f" >&2; exit 1; }
|
||||
done
|
||||
export MINDNET_APP_ENV_FILE MINDNET_ENV_FILE
|
||||
|
||||
# Vault-Mount und Präfix aus der systemd-.env ableiten (gleiches Verzeichnis wie heute).
|
||||
DERIVED="$(python3 deploy/appenv.py "$MINDNET_APP_ENV_FILE" "$MINDNET_ENV_FILE")"
|
||||
eval "$DERIVED"
|
||||
export MINDNET_VAULT_HOST_PATH MINDNET_VAULT_TARGET
|
||||
PREFIX="$MINDNET_EXPECTED_PREFIX"
|
||||
echo "$DERIVED"
|
||||
|
||||
SHA="$(git rev-parse --short=12 HEAD)"
|
||||
export MINDNET_IMAGE_TAG="$ENV-$SHA"
|
||||
LAST_GOOD="$(dirname "$MINDNET_ENV_FILE")/last_good_tag"
|
||||
|
||||
dc() { docker compose -f "deploy/compose.$ENV.yml" --env-file "$MINDNET_ENV_FILE" "$@"; }
|
||||
step() { printf '\n=== %s\n' "$*"; }
|
||||
show_logs() { dc ps || true; dc logs --tail 150 api ui || true; }
|
||||
published() { dc port "$1" "$2" | head -n 1 | sed 's/^0\.0\.0\.0:/127.0.0.1:/'; }
|
||||
|
||||
smoke() {
|
||||
python3 deploy/smoke.py --api "http://$(published api 8000)" --ui "http://$(published ui 8501)" \
|
||||
--prefix "$PREFIX" --require-data
|
||||
}
|
||||
|
||||
step "1/5 Container-Tests (ohne Netzwerk)"
|
||||
docker build -f deploy/Dockerfile --target test -t "mindnet:test-$SHA" .
|
||||
docker run --rm --network none "mindnet:test-$SHA"
|
||||
|
||||
step "2/5 Volle Testsuite (informativ, ohne Netzwerk)"
|
||||
if ! docker run --rm --network none "mindnet:test-$SHA" \
|
||||
python -m pytest tests -q -p no:cacheprovider --continue-on-collection-errors --basetemp=/tmp/pytest; then
|
||||
echo "WARNUNG: Testsuite nicht grün. Bekannte Fehler: docs/05_Development/05_docker_migration_plan.md"
|
||||
fi
|
||||
docker image rm "mindnet:test-$SHA" >/dev/null || true
|
||||
|
||||
step "3/5 Image bauen ($MINDNET_IMAGE_TAG)"
|
||||
dc build api ui
|
||||
|
||||
step "4/5 Preflight mit Erreichbarkeit (nur lesend)"
|
||||
dc run --rm --no-deps api preflight --live
|
||||
|
||||
step "5/5 Start ($MINDNET_IMAGE_TAG) und Smoke"
|
||||
if dc up -d --wait --no-build --remove-orphans && smoke; then
|
||||
echo "$MINDNET_IMAGE_TAG" > "$LAST_GOOD"
|
||||
echo "=== mindnet-$ENV läuft mit $MINDNET_IMAGE_TAG"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
show_logs
|
||||
PREV="$(cat "$LAST_GOOD" 2>/dev/null || true)"
|
||||
if [ "$ENV" = prod ] && [ -n "$PREV" ] && [ "$PREV" != "$MINDNET_IMAGE_TAG" ]; then
|
||||
step "Rollback auf $PREV"
|
||||
export MINDNET_IMAGE_TAG="$PREV"
|
||||
if dc up -d --wait --no-build --remove-orphans && smoke; then
|
||||
echo "Rollback erfolgreich; Deploy von $ENV-$SHA ist trotzdem fehlgeschlagen."
|
||||
else
|
||||
show_logs
|
||||
echo "ROLLBACK FEHLGESCHLAGEN, manueller Eingriff nötig." >&2
|
||||
fi
|
||||
fi
|
||||
exit 1
|
||||
@@ -0,0 +1,258 @@
|
||||
"""
|
||||
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)
|
||||
|
||||
|
||||
DEFAULT_VAULT_ROOT = "./vault_master" # Default aus app/config.py
|
||||
|
||||
|
||||
def check_vault() -> None:
|
||||
if not _flag("MINDNET_VAULT_REQUIRED", "true"):
|
||||
return
|
||||
root = Path(os.getenv("MINDNET_VAULT_ROOT") or DEFAULT_VAULT_ROOT)
|
||||
if not root.is_dir():
|
||||
raise PreflightError(f"Vault-Verzeichnis fehlt: '{root}'.")
|
||||
# Ein ausgefallenes NAS hinterlässt einen leeren Mountpunkt.
|
||||
try:
|
||||
empty = next(root.iterdir(), None) is None
|
||||
except OSError:
|
||||
raise PreflightError(f"Vault '{root}' nicht lesbar (NAS nicht gemountet?).") from None
|
||||
if empty:
|
||||
raise PreflightError(f"Vault '{root}' ist leer (NAS nicht gemountet?).")
|
||||
# Optional: zusätzlich eine bestimmte Datei verlangen (z. B. auf dem NAS-Vault).
|
||||
sentinel_name = os.getenv("MINDNET_VAULT_SENTINEL", "").strip()
|
||||
if sentinel_name:
|
||||
sentinel = root / sentinel_name
|
||||
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))
|
||||
@@ -0,0 +1,2 @@
|
||||
*.env
|
||||
!*.env.example
|
||||
Vendored
+15
@@ -0,0 +1,15 @@
|
||||
# Mindnet DEV (Container): NUR Container-Angaben. Liegt auf dem Host außerhalb von Git.
|
||||
# Die Anwendungskonfiguration kommt unverändert aus der .env der systemd-Instanz
|
||||
# (MINDNET_APP_ENV_FILE im Workflow). deploy/appenv.py lehnt hier andere Schlüssel ab,
|
||||
# damit diese Datei die Anwendungskonfiguration nicht überschreibt.
|
||||
|
||||
MINDNET_API_PORT=8012
|
||||
# API ohne Authentisierung; die UI erreicht sie intern. Für Zugriff von außen auf 0.0.0.0 setzen.
|
||||
MINDNET_API_BIND=127.0.0.1
|
||||
MINDNET_UI_PORT=8512
|
||||
MINDNET_UI_BIND=0.0.0.0
|
||||
|
||||
# Enthält die systemd-.env Cloud-Keys (OpenRouter/Gemini), startet der Container nur mit
|
||||
# ausdrücklicher Bestätigung. true = gleiches Verhalten wie heute: Vault-Inhalte gehen
|
||||
# ohne Privacy Gateway an den Cloud-Provider.
|
||||
MINDNET_ALLOW_CLOUD_EGRESS=false
|
||||
Vendored
+15
@@ -0,0 +1,15 @@
|
||||
# Mindnet PROD (Container): NUR Container-Angaben. Liegt auf dem Host außerhalb von Git.
|
||||
# Die Anwendungskonfiguration kommt unverändert aus der .env der systemd-Instanz
|
||||
# (MINDNET_APP_ENV_FILE im Workflow). deploy/appenv.py lehnt hier andere Schlüssel ab,
|
||||
# damit diese Datei die Anwendungskonfiguration nicht überschreibt.
|
||||
|
||||
MINDNET_API_PORT=8011
|
||||
# API ohne Authentisierung; die UI erreicht sie intern. Für Zugriff von außen auf 0.0.0.0 setzen.
|
||||
MINDNET_API_BIND=127.0.0.1
|
||||
MINDNET_UI_PORT=8511
|
||||
MINDNET_UI_BIND=0.0.0.0
|
||||
|
||||
# Enthält die systemd-.env Cloud-Keys (OpenRouter/Gemini), startet der Container nur mit
|
||||
# ausdrücklicher Bestätigung. true = gleiches Verhalten wie heute: Vault-Inhalte gehen
|
||||
# ohne Privacy Gateway an den Cloud-Provider.
|
||||
MINDNET_ALLOW_CLOUD_EGRESS=false
|
||||
@@ -0,0 +1,58 @@
|
||||
# VORLAGE, NICHT AKTIV: liegt absichtlich nicht unter .gitea/workflows/.
|
||||
# Aktivierung erst bei der Umschaltung (Gate G5, eigene Freigabe), und zwar im
|
||||
# selben Commit, der .gitea/workflows/deploy.yml (systemd) entfernt:
|
||||
# git rm .gitea/workflows/deploy.yml
|
||||
# git mv deploy/gitea-workflows/deploy-prod.yml .gitea/workflows/deploy-prod.yml
|
||||
# Sonst deployen bei jedem Push auf main beide Wege.
|
||||
#
|
||||
# Prod nur über Merge-Commit develop -> main (git merge --no-ff develop), wie bei Kansho.
|
||||
# Ablauf, Abbruchbedingungen und Rollback: deploy/deploy.sh.
|
||||
|
||||
name: Deploy mindnet PROD (Container)
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
concurrency:
|
||||
# Gleiche Gruppe wie der systemd-Workflow: nie zwei Prod-Deploys gleichzeitig.
|
||||
group: deploy-mindnet
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
# Runner auf dem Zielhost (heute llm-node). Bei einem Umzug auf einen anderen
|
||||
# Mini-PC nur das Label und die beiden Pfade anpassen.
|
||||
runs-on: linux_host
|
||||
env:
|
||||
# Unveränderte Konfiguration der systemd-Prod-Instanz.
|
||||
MINDNET_APP_ENV_FILE: /home/llmadmin/mindnet/.env
|
||||
# Nur Container-Angaben (Vorlage: deploy/env/prod.env.example).
|
||||
MINDNET_ENV_FILE: /home/llmadmin/docker/mindnet/container.env
|
||||
steps:
|
||||
# Ohne actions/checkout: kein Abruf von github.com (DNS/Internet auf dem Host
|
||||
# nicht nötig). Holt genau den Commit des Pushes vom eigenen Gitea, mit Job-Token.
|
||||
- name: Checkout
|
||||
run: |
|
||||
set -euo pipefail
|
||||
git init -q .
|
||||
git -c http.extraHeader="Authorization: token ${{ github.token }}" \
|
||||
fetch -q --depth 1 "${{ github.server_url }}/${{ github.repository }}.git" "${{ github.sha }}"
|
||||
git checkout -q --force FETCH_HEAD
|
||||
git clean -q -ffdx
|
||||
git log -1 --format='Checkout %H %s'
|
||||
|
||||
- name: Container-Datei beim ersten Lauf anlegen
|
||||
run: |
|
||||
set -euo pipefail
|
||||
install -d -m 0750 "$(dirname "$MINDNET_ENV_FILE")"
|
||||
if [ ! -f "$MINDNET_ENV_FILE" ]; then
|
||||
install -m 0600 deploy/env/prod.env.example "$MINDNET_ENV_FILE"
|
||||
echo "Container-Datei aus Vorlage angelegt: $MINDNET_ENV_FILE"
|
||||
fi
|
||||
docker version --format 'Docker {{.Server.Version}}'
|
||||
docker compose version
|
||||
|
||||
- name: Test, Build, Preflight, Start, Smoke (Rollback bei Fehler)
|
||||
run: bash deploy/deploy.sh prod
|
||||
@@ -0,0 +1,44 @@
|
||||
"""
|
||||
FILE: deploy/healthcheck.py
|
||||
DESCRIPTION: Docker-Healthcheck für API und UI.
|
||||
API ist nur gesund, wenn /healthz antwortet UND der Vault-Sentinel
|
||||
lesbar ist. Ein zur Laufzeit ausgefallenes NAS wird so als
|
||||
'unhealthy' sichtbar, statt still auf einem leeren Mountpunkt zu laufen.
|
||||
USAGE: healthcheck.py api | ui
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import sys
|
||||
import urllib.request
|
||||
from pathlib import Path
|
||||
|
||||
URLS = {
|
||||
"api": "http://127.0.0.1:8000/healthz",
|
||||
"ui": "http://127.0.0.1:8501/_stcore/health",
|
||||
}
|
||||
|
||||
|
||||
def main(mode: str) -> int:
|
||||
try:
|
||||
with urllib.request.urlopen(URLS[mode], timeout=5) as res:
|
||||
if res.status != 200:
|
||||
return 1
|
||||
except Exception as e:
|
||||
print(f"health: {mode} nicht erreichbar ({type(e).__name__})")
|
||||
return 1
|
||||
if mode == "api" and os.getenv("MINDNET_VAULT_REQUIRED", "true").lower() == "true":
|
||||
root = Path(os.getenv("MINDNET_VAULT_ROOT") or "./vault_master")
|
||||
sentinel_name = os.getenv("MINDNET_VAULT_SENTINEL", "").strip()
|
||||
try:
|
||||
ok = (root / sentinel_name).is_file() if sentinel_name else next(root.iterdir(), None) is not None
|
||||
except OSError:
|
||||
ok = False
|
||||
if not ok:
|
||||
print(f"health: Vault leer oder nicht lesbar ({root})")
|
||||
return 1
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "api"))
|
||||
@@ -0,0 +1,2 @@
|
||||
-c requirements.lock
|
||||
pytest>=8.4.2
|
||||
@@ -0,0 +1,28 @@
|
||||
colorama==0.4.6 ; sys_platform == 'win32' \
|
||||
--hash=sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44 \
|
||||
--hash=sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6
|
||||
# via
|
||||
# -c requirements.lock
|
||||
# pytest
|
||||
iniconfig==2.3.0 \
|
||||
--hash=sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730 \
|
||||
--hash=sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12
|
||||
# via pytest
|
||||
packaging==26.0 \
|
||||
--hash=sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4 \
|
||||
--hash=sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529
|
||||
# via
|
||||
# -c requirements.lock
|
||||
# pytest
|
||||
pluggy==1.6.0 \
|
||||
--hash=sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3 \
|
||||
--hash=sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746
|
||||
# via pytest
|
||||
pygments==2.19.2 \
|
||||
--hash=sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887 \
|
||||
--hash=sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b
|
||||
# via pytest
|
||||
pytest==9.0.2 \
|
||||
--hash=sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b \
|
||||
--hash=sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11
|
||||
# via -r requirements-test.in
|
||||
@@ -0,0 +1,24 @@
|
||||
# Laufzeit-Abhängigkeiten für die Container-Images (API + UI).
|
||||
# Abgeleitet aus requirements.txt OHNE torch, sentence-transformers und pytest:
|
||||
# - app/embeddings.py (MiniLM) wird von keinem eingebundenen Router importiert;
|
||||
# Embeddings laufen über Ollama (embedding_expert, nomic-embed-text, 768 Dim.).
|
||||
# - pytest steckt nur im Test-Target (requirements-test.in).
|
||||
# Lock neu erzeugen: siehe docs/04_Operations/04_docker_deployment.md, Abschnitt "Lock".
|
||||
fastapi>=0.116.1
|
||||
uvicorn[standard]>=0.35.0
|
||||
httpx>=0.28.1
|
||||
qdrant-client>=1.15.1
|
||||
pydantic>=2.11.7
|
||||
numpy>=2.3.2
|
||||
python-frontmatter>=1.1.0
|
||||
markdown-it-py>=3.0.0
|
||||
PyYAML>=6.0.2
|
||||
python-slugify>=8.0.4
|
||||
python-dotenv>=1.1.1
|
||||
requests>=2.32.5
|
||||
tqdm>=4.67.1
|
||||
streamlit>=1.39.0
|
||||
streamlit-agraph>=0.0.45
|
||||
st-cytoscape
|
||||
google-genai>=0.3.0
|
||||
openai>=1.50.0
|
||||
File diff suppressed because it is too large.
Load diff
+113
@@ -0,0 +1,113 @@
|
||||
"""
|
||||
FILE: deploy/smoke.py
|
||||
DESCRIPTION: Nicht-schreibender Smoke-Test gegen einen laufenden Mindnet-Stack,
|
||||
aus Sicht des Hosts über die veröffentlichten Ports. Nur Standardbibliothek,
|
||||
läuft daher direkt auf dem Runner (python3), ohne venv.
|
||||
- API /healthz: Status ok, erwartetes Collection-Präfix
|
||||
- API /admin/stats: Vektorgröße 768; API erreicht Qdrant (Collection-Counts)
|
||||
- UI /_stcore/health
|
||||
--require-data (Prod): alle Collections vorhanden und Notes nicht leer.
|
||||
VERSION: 1.0.0
|
||||
STATUS: Active
|
||||
USAGE: smoke.py --api http://127.0.0.1:8012 --ui http://127.0.0.1:8512 --prefix mindnet_dev [--require-data]
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
import time
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
|
||||
EXPECTED_VECTOR_SIZE = 768
|
||||
|
||||
|
||||
class SmokeError(RuntimeError):
|
||||
pass
|
||||
|
||||
|
||||
def _get(url: str, timeout: float = 15) -> bytes:
|
||||
try:
|
||||
with urllib.request.urlopen(url, timeout=timeout) as res:
|
||||
return res.read()
|
||||
except urllib.error.HTTPError as e:
|
||||
raise SmokeError(f"{url}: HTTP {e.code}") from None
|
||||
except (urllib.error.URLError, OSError) as e:
|
||||
raise SmokeError(f"{url} nicht erreichbar ({getattr(e, 'reason', e)})") from None
|
||||
|
||||
|
||||
def _get_json(url: str) -> dict:
|
||||
try:
|
||||
return json.loads(_get(url))
|
||||
except ValueError:
|
||||
raise SmokeError(f"{url} liefert kein JSON") from None
|
||||
|
||||
|
||||
def check_api(api: str, prefix: str, require_data: bool) -> list[str]:
|
||||
"""Gibt Warnungen zurück; harte Fehler als SmokeError."""
|
||||
health = _get_json(f"{api}/healthz")
|
||||
if health.get("status") != "ok":
|
||||
raise SmokeError(f"/healthz meldet {health.get('status')!r}")
|
||||
if health.get("prefix") != prefix:
|
||||
raise SmokeError(f"API nutzt Präfix {health.get('prefix')!r}, erwartet {prefix!r}")
|
||||
|
||||
stats = _get_json(f"{api}/admin/stats")
|
||||
size = (stats.get("config") or {}).get("vector_size")
|
||||
if size != EXPECTED_VECTOR_SIZE:
|
||||
raise SmokeError(f"API-Vektorgröße {size}, erwartet {EXPECTED_VECTOR_SIZE}")
|
||||
|
||||
warnings = []
|
||||
collections = stats.get("collections") or {}
|
||||
for kind in ("notes", "chunks", "edges"):
|
||||
entry = collections.get(kind) or {}
|
||||
count = entry.get("count", -1)
|
||||
if count < 0:
|
||||
# -1: Collection fehlt oder Qdrant ist aus dem API-Container nicht erreichbar.
|
||||
msg = f"Collection {entry.get('name', kind)!r} nicht lesbar (fehlt oder Qdrant nicht erreichbar)"
|
||||
if require_data:
|
||||
raise SmokeError(msg)
|
||||
warnings.append(msg)
|
||||
if require_data and (collections.get("notes") or {}).get("count", 0) <= 0:
|
||||
raise SmokeError("Notes-Collection ist leer")
|
||||
return warnings
|
||||
|
||||
|
||||
def check_ui(ui: str) -> None:
|
||||
body = _get(f"{ui}/_stcore/health").decode("utf-8", "replace").strip()
|
||||
if body != "ok":
|
||||
raise SmokeError(f"UI-Health meldet {body!r}")
|
||||
|
||||
|
||||
def run(api: str, ui: str, prefix: str, require_data: bool = False, attempts: int = 1, delay: float = 5) -> int:
|
||||
api, ui = api.rstrip("/"), ui.rstrip("/")
|
||||
for attempt in range(1, attempts + 1):
|
||||
try:
|
||||
warnings = check_api(api, prefix, require_data)
|
||||
check_ui(ui)
|
||||
except SmokeError as e:
|
||||
if attempt == attempts:
|
||||
print(f"smoke: FEHLER: {e}", file=sys.stderr)
|
||||
return 1
|
||||
time.sleep(delay)
|
||||
continue
|
||||
for w in warnings:
|
||||
print(f"smoke: WARNUNG: {w}")
|
||||
print(f"smoke: OK (api={api}, ui={ui}, prefix={prefix})")
|
||||
return 0
|
||||
return 1
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__.split("USAGE:")[0])
|
||||
parser.add_argument("--api", required=True)
|
||||
parser.add_argument("--ui", required=True)
|
||||
parser.add_argument("--prefix", required=True)
|
||||
parser.add_argument("--require-data", action="store_true")
|
||||
parser.add_argument("--attempts", type=int, default=3)
|
||||
args = parser.parse_args(argv)
|
||||
return run(args.api, args.ui, args.prefix, args.require_data, args.attempts)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,394 @@
|
||||
# Mindnet Causal Assistant – Dokumentation der bisher erreichten Resultate (0.4.x) + Architektur, Konfiguration & Strategien
|
||||
|
||||
> Stand: basierend auf den beobachteten Chain-Inspector-Logs und den zuletzt beschriebenen Implementierungen in 0.4.6/0.4.x.
|
||||
> Ziel dieser Doku: Eine **einheitliche, belastbare Basis**, damit Weiterentwicklung (0.5.x/0.6.x) nicht mehr “im Kreis” läuft.
|
||||
|
||||
---
|
||||
|
||||
## 1) Zweck & Gesamtziel von Mindnet
|
||||
|
||||
Mindnet soll in einem Obsidian Vault **kausale/argumentative Zusammenhänge** als Graph abbilden und daraus **nützliche Diagnosen** ableiten:
|
||||
|
||||
- **Graph-Aufbau:** Notes/Sections als Knoten, Links/Kanten als gerichtete Beziehungen (z.B. *wirkt_auf*, *resulted_in*, *depends_on* …).
|
||||
- **Analyse aus einem Kontext:** Nutzer steht in einer Note an einer bestimmten Überschrift/Section → Mindnet analysiert lokale Nachbarschaft + Pfade im Graphen.
|
||||
- **Template Matching:** Einordnen der gefundenen Knoten/Kanten in “Kettenmuster” (Chain Templates) wie z.B. *trigger → transformation → outcome* oder *loop_learning*.
|
||||
- **Findings (Gap-Heuristiken):** Hinweise wie “fehlende Slots”, “fehlende Links”, “unmapped edge types”, “einseitige Konnektivität”, etc.
|
||||
→ Ziel: **Nutzer konkret zum besseren Graphen führen**, ohne “Noisy” zu sein.
|
||||
|
||||
---
|
||||
|
||||
## 2) Begriffe & Datenmodell (so arbeitet der Chain Inspector)
|
||||
|
||||
### 2.1 Kontext (Context)
|
||||
Der Chain Inspector läuft immer gegen einen **aktuellen Kontext**:
|
||||
- `file`: aktuelle Note (z.B. `Tests/03_insight_transformation.md`)
|
||||
- `heading`: aktuelle Section (z.B. `Kern`)
|
||||
- `zoneKind`: i.d.R. `content`
|
||||
|
||||
Das ist wichtig, weil Kanten teils **section-spezifisch** sind und teils (geplant/teilweise offen) **note-weit** gelten könnten.
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Knoten (Nodes)
|
||||
Ein Knoten ist im Report meist referenziert als:
|
||||
- `file + heading` (z.B. `Tests/01_experience_trigger.md:Kontext`)
|
||||
- plus abgeleitete Metadaten wie `noteType` (z.B. experience, insight, decision, event)
|
||||
|
||||
**noteType** ist entscheidend fürs Template Matching (Slots).
|
||||
|
||||
---
|
||||
|
||||
### 2.3 Kanten (Edges)
|
||||
Eine Kante hat typischerweise:
|
||||
- `rawEdgeType`: Original-Typ aus Markdown/Notation (z.B. `wirkt_auf`, `resulted_in`, `depends_on`, `derived_from`, …)
|
||||
- `from`: Quelle (file:heading)
|
||||
- `to`: Ziel (file:heading)
|
||||
- `scope`: Gültigkeit / Herkunft
|
||||
- `section`: Edge ist “voll gültig” für die Section
|
||||
- `candidate`: Edge ist nur Kandidat/unsicher, wird optional zugelassen
|
||||
- (geplant/offen) `note`: Edge gilt note-weit (unabhängig von Section)
|
||||
- `evidence`: Fundstelle (file, sectionHeading, lineRange)
|
||||
|
||||
---
|
||||
|
||||
## 3) Erreichte Resultate in 0.4.x (verifiziert)
|
||||
|
||||
### 3.1 includeCandidates – Kandidatenkanten funktionieren wie erwartet
|
||||
**Ergebnis (bereits mehrfach in Logs verifiziert):**
|
||||
- Wenn `includeCandidates=false`, werden Kanten mit `scope: candidate` **im effektiven Graphen ausgefiltert**.
|
||||
- Wenn `includeCandidates=true`, werden Kandidatenkanten **als incoming/outgoing** berücksichtigt und tauchen in `neighbors`/`paths` auf.
|
||||
|
||||
**Implikation:**
|
||||
- Das System kann “unsichere” oder “LLM-vorschlagene” Verbindungen existieren lassen, ohne in jedem Lauf die Analyse zu verfälschen.
|
||||
- In “Discovery” kann man Kandidaten zulassen (mehr Explorationspower).
|
||||
- In “Decisioning” kann man Kandidaten typischerweise sperren (mehr Verlässlichkeit).
|
||||
|
||||
---
|
||||
|
||||
### 3.2 required_links: Strict vs Soft Mode – missing_link_constraints Unterdrückung ist umgesetzt
|
||||
**Problem (historisch):**
|
||||
- `missing_link_constraints` wurde teilweise auch dann ausgegeben, wenn `required_links=false` (Soft Mode) aktiv war → unnötig “noisy”.
|
||||
|
||||
**Fix (laut Cursor-Report umgesetzt + Tests):**
|
||||
- `missing_link_constraints` wird nur erzeugt, wenn `effectiveRequiredLinks === true`.
|
||||
- Es gibt eine definierte Auflösungsreihenfolge für `required_links`:
|
||||
|
||||
**Resolution Order (effective required_links):**
|
||||
1. `template.matching?.required_links`
|
||||
2. `profile.required_links`
|
||||
3. `defaults.matching?.required_links`
|
||||
4. Fallback: `false`
|
||||
|
||||
**Transparenz bleibt erhalten:**
|
||||
- `satisfiedLinks` und `requiredLinks` werden weiterhin im Report angezeigt.
|
||||
- `linksComplete` bleibt als technischer Wert im Report bestehen.
|
||||
- **Nur** das Finding `missing_link_constraints` wird unterdrückt, nicht die Fakten.
|
||||
|
||||
**Implikation:**
|
||||
- Soft Mode (= required_links=false) ist jetzt ruhig genug, um “Entdeckung” zu unterstützen.
|
||||
- Strict Mode (= required_links=true) eignet sich für harte Qualitätskontrolle.
|
||||
|
||||
---
|
||||
|
||||
### 3.3 “Healthy graph” → Findings leer ([]), Template “confirmed”
|
||||
Wenn Slots **und** geforderte Links erfüllt sind (z.B. `trigger_transformation_outcome` mit 2/2 Links),
|
||||
dann ist `findings: []` das erwartete Ergebnis.
|
||||
|
||||
**Implikation:**
|
||||
- Das ist das zentrale “Green Path”-Signal: Graph ist konsistent für das gewählte Template/Profil.
|
||||
|
||||
---
|
||||
|
||||
### 3.4 Unmapped edges werden erkannt (Diagnose)
|
||||
Wenn ein `rawEdgeType` nicht in die kanonischen Rollen/Edge-Rollen abgebildet werden kann, tauchen typischerweise Diagnosen auf:
|
||||
- `edgesUnmapped > 0`
|
||||
- Findings wie `no_causal_roles` oder link constraints bleiben unerfüllt
|
||||
|
||||
**Implikation:**
|
||||
- Das Rollen-Mapping (chain_roles.yaml) ist “critical path”: wenn ein Edge-Typ nicht gemappt wird, bricht oft der kausale Interpretationspfad.
|
||||
|
||||
---
|
||||
|
||||
## 4) Was ist (noch) offen – echtes nächstes Verifikationsziel
|
||||
|
||||
### 4.1 Note-Level Edges / Note-Scope (“für jede Sektion gültig”)
|
||||
Es existiert ein Konzept/Einbau: In `02_event_trigger_detail` gibt es einen Bereich, der Kanten **auf Note-Ebene** definieren soll (unabhängig von aktueller Section).
|
||||
|
||||
**Offen ist die robuste Verifikation (oder Implementierung), dass:**
|
||||
- diese Edges auch dann gelten, wenn der Cursor in einer anderen Section derselben Note steht,
|
||||
- idealerweise mit klar erkennbarer Kennzeichnung wie `scope: note` im Report.
|
||||
|
||||
**Warum ist das wichtig?**
|
||||
- Das ermöglicht “globaler Kontext” pro Note, ohne alles in jede Section duplizieren zu müssen.
|
||||
- Es ist eine UX-Optimierung: Nutzer kann “Meta-Verbindungen” an einer Stelle pflegen.
|
||||
|
||||
---
|
||||
|
||||
## 5) Konfigurationsdateien – Rolle & Interpretation (Mindnet-Strategie)
|
||||
|
||||
> Die folgenden Bereiche beschreiben eine **saubere, konsistente Interpretation**, wie Mindnet die Configs verwenden sollte.
|
||||
> Konkrete Keys, die in Logs sichtbar waren (z.B. required_links, min_slots_filled_for_gap_findings, min_score_for_gap_findings) sind hier berücksichtigt.
|
||||
|
||||
### 5.1 chain_templates.yaml – “Welche Ketten gibt es, wie werden sie gematcht?”
|
||||
**Zweck:**
|
||||
- Definiert Templates (Muster), z.B.:
|
||||
- `trigger_transformation_outcome`
|
||||
- `loop_learning`
|
||||
- ggf. weitere (constraint_to_adaptation usw.)
|
||||
|
||||
**Template enthält typischerweise:**
|
||||
- Slots (Rollen für Knoten): z.B. `trigger`, `transformation`, `outcome`, `experience`, `learning`, `behavior`, `feedback`
|
||||
- Required Link Constraints (welche Slot-zu-Slot Verbindungen zwingend sind)
|
||||
- Scoring/Matching-Parameter (ggf. weights, thresholds)
|
||||
- Optional: template-level override für `required_links`
|
||||
|
||||
**Matching-Profile (wie in Logs sichtbar):**
|
||||
- z.B. Profile: `discovery`, `decisioning`
|
||||
- Parameter im Profil (sichtbar in Logs):
|
||||
- `required_links` (strict vs soft)
|
||||
- `min_slots_filled_for_gap_findings`
|
||||
- `min_score_for_gap_findings`
|
||||
- ggf. `maxTemplateMatches`
|
||||
|
||||
**Interpretation:**
|
||||
- Templates liefern die “Soll-Struktur”
|
||||
- Profile bestimmen “Wie streng” wir die Soll-Struktur im jeweiligen Workflow bewerten
|
||||
|
||||
---
|
||||
|
||||
### 5.2 chain_roles.yaml – “Welche rawEdgeTypes zählen als welche Rollen?”
|
||||
**Zweck:**
|
||||
- Mappt `rawEdgeType` → kanonische Rollen/EdgeRoles (z.B. `causal`, `influences`, `enables_constraints`, `provenance`).
|
||||
- Diese Rollen sind Grundlage für:
|
||||
- `no_causal_roles` Finding
|
||||
- Link-Constraint-Satisfaction (Template erwartet “causal” zwischen Slots)
|
||||
- Matching Score (welche Edges zählen für welches Template)
|
||||
|
||||
**Interpretation:**
|
||||
- Wenn ein Edge-Typ nicht gemappt ist:
|
||||
- Edge kann trotzdem im Graph auftauchen,
|
||||
- aber Template/Constraint-Logik kann ihn nicht “verstehen” → führt zu Findings.
|
||||
|
||||
---
|
||||
|
||||
### 5.3 analysis_policies.yaml – “Wie noisy dürfen Findings sein?”
|
||||
**Zweck:**
|
||||
- Zentrale Policies für Findings:
|
||||
- welche Finding-Codes existieren
|
||||
- Default-Severity (info/warn/error)
|
||||
- Profilabhängige Overrides
|
||||
- Unterdrückungsregeln (z.B. suppress in soft mode, suppress wenn confirmed, suppress wenn Score hoch…)
|
||||
|
||||
**Interpretation:**
|
||||
- Policies sind “produktseitige UX-Regeln”:
|
||||
- Discovery: eher informativ, weniger warn
|
||||
- Decisioning: klare Warnungen, wenn Qualität fehlt
|
||||
- Der bereits umgesetzte Fix (`missing_link_constraints` nur in strict) ist exakt so eine Policy-Entscheidung (auch wenn technisch im Inspector gelöst).
|
||||
|
||||
---
|
||||
|
||||
## 6) Ablauf des Chain Inspectors (Vorgehensweise in Mindnet)
|
||||
|
||||
Hier ist ein konsistenter “Pipeline”-Ablauf, der zu den Logs passt:
|
||||
|
||||
### Schritt 1: Kontext bestimmen
|
||||
- Aktuelle Datei + aktuelle Section/Heading
|
||||
|
||||
### Schritt 2: Edges aus aktueller Note laden
|
||||
- Outgoing aus der aktuellen Section extrahieren (oder aus einem definierten Block)
|
||||
- (optional/offen) Note-Level Edges ebenfalls laden und für jede Section gültig machen
|
||||
|
||||
### Schritt 3: Nachbarn laden
|
||||
- Backlinks (Notes, die auf die aktuelle Note verlinken) → incoming Kandidatenquellen
|
||||
- Outgoing Neighbor Notes (Notes, auf die aktuelle Note verweist) → Nachbarschaft erweitern
|
||||
|
||||
### Schritt 4: Edges aus Neighbor Notes laden
|
||||
- Aus den verlinkenden Notes die Edges extrahieren, die auf die aktuelle Note/Section zielen
|
||||
- Canonicalization: rawEdgeTypes via chain_roles.yaml in Rollen überführen
|
||||
|
||||
### Schritt 5: Kandidatenfilter / Scopefilter anwenden
|
||||
- Wenn `includeCandidates=false`:
|
||||
- `scope: candidate` aus effective graph entfernen
|
||||
- Optional weitere Filter:
|
||||
- includeNoteLinks / includeSectionLinks
|
||||
- direction (forward/backward/both)
|
||||
- maxDepth (Traversal)
|
||||
|
||||
### Schritt 6: Pfade berechnen (Paths)
|
||||
- Forward/Backward (oder both)
|
||||
- BFS/DFS bis `maxDepth`
|
||||
- Resultat: Pfadlisten mit nodes + edges
|
||||
|
||||
### Schritt 7: Template Matching
|
||||
- Kandidatenknoten für Slots finden (via noteType + Nähe + Pfade)
|
||||
- Links/Constraints prüfen (erwartete slot→slot Beziehungen)
|
||||
- Score berechnen (z.B. per:
|
||||
- Slots erfüllt
|
||||
- Link constraints erfüllt
|
||||
- “RoleEvidence” passend)
|
||||
|
||||
### Schritt 8: Findings berechnen (Gap-Heuristics)
|
||||
Beispiele:
|
||||
- `missing_slot_*` wenn wichtige Slots fehlen (abhängig von Profil-Thresholds)
|
||||
- `one_sided_connectivity` wenn nur incoming oder nur outgoing
|
||||
- `no_causal_roles` wenn Edges da, aber keine causal Rollen im effektiven Graph
|
||||
- `missing_link_constraints` nur wenn effectiveRequiredLinks=true und slotsComplete=true, requiredLinks>0, linksComplete=false
|
||||
|
||||
### Schritt 9: Report ausgeben
|
||||
- context, settings, neighbors, paths, findings, analysisMeta, templateMatches
|
||||
- Transparenz: satisfiedLinks/requiredLinks/linksComplete bleiben sichtbar
|
||||
|
||||
---
|
||||
|
||||
## 7) Strategien, die Mindnet verfolgen kann (Produkt-/UX-Strategie)
|
||||
|
||||
### Strategie A: Discovery (Exploration)
|
||||
**Ziel:** Möglichst schnell “wo könnte eine sinnvolle Kette entstehen?” finden.
|
||||
- required_links = false (Soft Mode)
|
||||
- includeCandidates = true (optional)
|
||||
- findings eher informativ (info), weniger warn
|
||||
- Templates mehr als Vorschläge (“plausible/weak”), nicht als harte Bewertung
|
||||
|
||||
**Vorteil:** Nutzer bekommt schnell Hypothesen.
|
||||
**Risiko:** Mehr Noise, mehr falsche Kandidaten – muss per Policy gedämpft werden.
|
||||
|
||||
---
|
||||
|
||||
### Strategie B: Decisioning (Qualitätskontrolle)
|
||||
**Ziel:** Prüfung, ob eine Kette “wirklich steht” und als belastbar gelten kann.
|
||||
- required_links = true (Strict Mode)
|
||||
- includeCandidates = false
|
||||
- findings: warn, wenn Slots/Links fehlen
|
||||
- “confirmed” nur wenn link constraints komplett
|
||||
|
||||
**Vorteil:** Qualitätssicherung & Verlässlichkeit.
|
||||
**Risiko:** Nutzer fühlt sich “blockiert”, wenn Graph noch im Aufbau ist.
|
||||
|
||||
---
|
||||
|
||||
### Strategie C: Progressive Disclosure (hybrid)
|
||||
**Ziel:** Nutzer nicht überfordern, aber zielgerichtet verbessern.
|
||||
- Soft Mode für Einstieg
|
||||
- Button/Toggle: “Strict prüfen”
|
||||
- Candidate Edges als Vorschlag-Klasse (UI: “proposed edges”)
|
||||
- Findings priorisieren: erst fehlende Slots, dann fehlende Links, dann Detail-Qualität
|
||||
|
||||
---
|
||||
|
||||
## 8) Wie ein “kausaler Retriever” funktionieren könnte (Causal Retriever)
|
||||
|
||||
Ein kausaler Retriever ist die Komponente, die aus dem Vault/Graphen **relevante Kausalkontexte** für den aktuellen Abschnitt liefert – idealerweise deterministisch, skalierbar und template-aware.
|
||||
|
||||
### 8.1 Retrieval-Ziele
|
||||
- Finde Knoten/Edges, die **kausal relevant** sind zum aktuellen Kontext:
|
||||
- Ursachen (backward)
|
||||
- Wirkungen/Entscheidungen (forward)
|
||||
- Bedingungen/Constraints (seitlich)
|
||||
- Gib nicht nur Knoten zurück, sondern:
|
||||
- Pfade (explainable)
|
||||
- Evidence (wo steht das)
|
||||
- Role-Interpretation (warum ist das causal/influences/etc.)
|
||||
|
||||
### 8.2 Retrieval-Inputs
|
||||
- startNode = current section
|
||||
- direction = forward/backward/both
|
||||
- maxDepth
|
||||
- roleFilter (optional): nur causal/influences/enables_constraints
|
||||
- scopeFilter: includeCandidates, includeNoteLevel
|
||||
- templateBias: bevorzugte Pfadformen (z.B. “experience→insight→decision”)
|
||||
|
||||
### 8.3 Retrieval-Algorithmus (praktisch)
|
||||
**Variante 1: BFS mit Rolle-Gewichtung**
|
||||
- BFS über Kanten
|
||||
- Priorität/Score pro Frontier:
|
||||
- causal > influences > provenance
|
||||
- section-scope > note-scope > candidate (wenn candidates eingeschaltet, sonst candidate=∞)
|
||||
- Stop, wenn:
|
||||
- maxDepth erreicht
|
||||
- genug Top-N Pfade gesammelt (z.B. topNUsed)
|
||||
|
||||
**Variante 2: Template-driven Retrieval**
|
||||
- Wenn ein Template im Fokus ist:
|
||||
- suche explizit nach Slot-Knoten (noteType matching)
|
||||
- suche dann die minimalen Verbindungen, die Constraints erfüllen
|
||||
- Gute Option für “Decisioning”: deterministisch prüfen.
|
||||
|
||||
**Variante 3: Two-phase Retrieval**
|
||||
1) Kandidaten finden (Slots)
|
||||
2) Verbindungen prüfen (Constraints)
|
||||
→ Liefert sehr gut “warum fehlt Link X?” Diagnosen.
|
||||
|
||||
### 8.4 Output-Format
|
||||
- `neighbors` (incoming/outgoing, mit evidence)
|
||||
- `paths` (forward/backward, nodes+edges)
|
||||
- plus “slot candidates” optional (für UI)
|
||||
|
||||
---
|
||||
|
||||
## 9) Empfehlungen für robuste Tests (damit ihr nicht wieder im Kreis lauft)
|
||||
|
||||
### Was ist bereits ausreichend getestet (nicht wiederholen)
|
||||
- includeCandidates Filterverhalten ✅
|
||||
- missing_link_constraints Unterdrückung bei required_links=false ✅
|
||||
- strict/soft required_links via profile/template override ✅
|
||||
- “healthy graph” ergibt findings: [] ✅
|
||||
- unmapped edge type triggert Diagnose ✅
|
||||
|
||||
### Was als einziges “neues” Testziel für Abschluss 0.4.x/Start 0.5.x taugt
|
||||
- **Note-level edges / note-scope**: gelten Kanten “global” pro Note oder nicht?
|
||||
|
||||
**Minimal-Testdefinition (einmalig, reproduzierbar):**
|
||||
1) In `02_event_trigger_detail.md` einen klaren Note-Level Block definieren (z.B. “## Note-Verbindungen”).
|
||||
2) Edge dort definieren, die auf eine andere Note/Section zeigt.
|
||||
3) Cursor in einer anderen Section derselben Note platzieren (z.B. “## Detail” oder “## Extra”).
|
||||
4) Chain Inspector laufen lassen.
|
||||
5) Erwartung:
|
||||
- Edge erscheint trotzdem als outgoing/incoming
|
||||
- evidence zeigt auf den Note-Level Block
|
||||
- ideal: `scope: note`
|
||||
|
||||
Wenn das FAIL ist → klarer 0.5.0 Task.
|
||||
|
||||
---
|
||||
|
||||
## 10) Implikationen für 0.5.x / 0.6.x (wohin sinnvoll weiter)
|
||||
|
||||
### 0.5.x (Stabilisierung)
|
||||
- Note-level edge scope finalisieren (inkl. Report-Transparenz)
|
||||
- policies (analysis_policies) als zentrale Noise-Steuerung weiter ausbauen
|
||||
- Debug/Explainability weiter verbessern (effectiveRequiredLinks pro Match explizit ausgeben)
|
||||
|
||||
### 0.6.x (UX & Workflows)
|
||||
- Actionable Findings: “Was genau soll ich ändern?” inkl. Vorschlagtext oder Snippet
|
||||
- UI-Toggles: Strict/Soft, Candidates on/off
|
||||
- Template Authoring Tools: Linter, “Warum kein Match?”
|
||||
|
||||
---
|
||||
|
||||
## 11) Kurzes “Was heißt das für Mindnet im Alltag?”
|
||||
- Im Discovery-Modus: Mindnet ist ein **Explorationswerkzeug** (Hypothesen + Hinweise, wenig Warnungen).
|
||||
- Im Decisioning-Modus: Mindnet ist ein **Qualitätsprüfer** (strict, wenige false positives).
|
||||
- Der nächste große Hebel ist Note-scope: Damit wird Pflege einfacher und Ketten werden “wartbarer”.
|
||||
|
||||
---
|
||||
|
||||
## 12) Appendix: Beispielhafte Report-Signale (Interpretationshilfe)
|
||||
|
||||
- `findings: []` + `confidence: confirmed`
|
||||
→ Template passt sauber (Slots + Links vollständig im gewählten Modus).
|
||||
|
||||
- `linksComplete=false` aber `required_links=false` und **kein** `missing_link_constraints`
|
||||
→ Soft Mode: bewusst kein “Warn-Noise”, aber Transparenz bleibt.
|
||||
|
||||
- `no_causal_roles`
|
||||
→ Edges existieren, aber keine davon wird als “causal” interpretiert (Mapping oder rawEdgeType Problem).
|
||||
|
||||
- `edgesUnmapped > 0`
|
||||
→ chain_roles unvollständig oder Edge-Typ ist neu/fehlerhaft geschrieben.
|
||||
|
||||
- `effectiveIncoming=0` bei includeCandidates=false, aber incoming candidate-edge existiert
|
||||
→ Filter funktioniert wie geplant.
|
||||
|
||||
---
|
||||
|
||||
ENDE
|
||||
@@ -0,0 +1,223 @@
|
||||
<!-- FILE: konzept_zielbild_kausales_retrieval_mindnet.md -->
|
||||
---
|
||||
id: konzept_zielbild_kausales_retrieval_mindnet
|
||||
title: Konzept & Zielbild – Kausalketten-Prüfung und kausales Retrieval für Mindnet (Qdrant)
|
||||
type: concept
|
||||
status: draft
|
||||
created: 2026-01-13
|
||||
lang: de
|
||||
tags:
|
||||
- mindnet
|
||||
- obsidian
|
||||
- knowledge_graph
|
||||
- causal_chains
|
||||
- retrieval
|
||||
|
||||
|
||||
---
|
||||
|
||||
# Konzept & Zielbild – Kausalketten-Prüfung und kausales Retrieval für Mindnet (Qdrant)
|
||||
|
||||
## Ziel
|
||||
Mindnet soll zu beliebigen Fragestellungen **die richtigen Notizen** nicht nur über semantische Nähe (Embeddings), sondern über **kausale Relevanz** finden.
|
||||
Parallel soll ein Authoring-Assistent helfen, Obsidian-Notizen so anzulegen, dass Kausalketten **formal konsistent** und **traversierbar** sind.
|
||||
|
||||
---
|
||||
|
||||
## Ausgangslage / Problem
|
||||
- Der Wissensgraph wird in Qdrant gepflegt; aktuelles Retrieval basiert primär auf **Gewichtung + semantischer Nähe**.
|
||||
- Ergebnis: thematisch nahe Treffer, aber oft **nicht antwortrelevant** (fehlende Ursachen-/Folgenbezüge).
|
||||
- Obsidian-Notizen enthalten Edges (Vorwärts/Rückwärts); Qualität hängt von:
|
||||
- korrekter Relation (Kausalität vs Chronologie),
|
||||
- konsistenten Node-Namen,
|
||||
- Inversen (gegenläufigen Beziehungen),
|
||||
- sauberer Typisierung ab.
|
||||
|
||||
---
|
||||
|
||||
## Grundannahmen
|
||||
- Viele Antworten benötigen einen **Erklärungspfad** statt eines Einzel-Treffers:
|
||||
- Ursache → Mechanismus/Transformation → Entscheidung → Wirkung → Rückkopplung
|
||||
- Kausalität ist im Graph als gerichtete Kanten modelliert und über inverse Typen **bidirektional navigierbar**:
|
||||
- `resulted_in` ⇄ `caused_by`
|
||||
- `followed_by` ⇄ `preceeded_by`
|
||||
- `derived_from` ⇄ `source_of`
|
||||
- `impacts` ⇄ `impacted_by`
|
||||
|
||||
---
|
||||
|
||||
## System-Zielbild (2 Hauptkomponenten)
|
||||
|
||||
### 1) Authoring-Assistent (Obsidian Graph Linter + Chain Explorer)
|
||||
Zweck: Qualitätssicherung beim Erstellen/Ändern von Notizen.
|
||||
|
||||
**Kernfunktionen**
|
||||
- **Formale Prüfungen**
|
||||
- Canonical Edge vs Alias (Normalisierung nach `edge_vocabulary`)
|
||||
- Zielnoten existieren / leere Links als `open_question` oder TODO markieren
|
||||
- Tippfehler/Node-Splitting erkennen (mehrere Schreibweisen desselben Knoten)
|
||||
- Edge-Typ zulässig für Note-Typ (z.B. keine Kausal-Edges aus `open_question`)
|
||||
- **Semantische Plausibilität (regelbasiert)**
|
||||
- Chronologie (`followed_by`) ≠ Kausalität (`resulted_in`)
|
||||
- Hub-/Index-Noten nutzen primär `related_to/consists_of` statt Kausalität
|
||||
- Prinzipien bevorzugt `derived_from/based_on` statt pauschal `caused_by`
|
||||
- **Ketten-Integrität**
|
||||
- „Gap“-Warnungen (Sprünge ohne Zwischennoten)
|
||||
- Zyklen ohne Sinn (A caused_by B und B caused_by A)
|
||||
- Mehrfachursachen transparent markieren
|
||||
|
||||
**Outputs**
|
||||
- Lint-Report pro Note (Fehler/Warnung/Empfehlung)
|
||||
- Chain-Preview (2–4 Schritte vorwärts/rückwärts)
|
||||
- Optional: Auto-Fix-Vorschläge (Alias→Canonical, Link-Normalisierung, Inversen ergänzen)
|
||||
|
||||
---
|
||||
|
||||
### 2) Mindnet Retrieval: Hybrid aus Embeddings + Graph Traversal + Reranking
|
||||
Zweck: Aus einer Frage automatisch eine **kleine, kausal zusammenhängende** Menge von Notizen auswählen.
|
||||
|
||||
**Pipeline**
|
||||
1. **Seed Retrieval (Qdrant Embeddings)**
|
||||
- Top-K Kandidaten (z.B. 30) als Startpunkte
|
||||
- Optional: Filter nach Node-Typ (z.B. bei „Welche Entscheidungen…“)
|
||||
|
||||
2. **Intent-Klassifikation (Frage → Richtung & Kettenform)**
|
||||
- Regelbasiert (Start) oder später ML-Classifier
|
||||
- Output: `{direction, preferred_edges, target_types, max_hops, need_explanation_chain}`
|
||||
|
||||
3. **Graph Expansion (Multi-Source Multi-Hop Traversal)**
|
||||
- Expandiert von Seeds 1–3 Hops (typisch 2–4)
|
||||
- Richtungslogik:
|
||||
- „Warum/Ursache“ → rückwärts (`caused_by`, `preceeded_by`, `derived_from`)
|
||||
- „Folgen/Ergebnis“ → vorwärts (`resulted_in`, `followed_by`, `impacts`)
|
||||
- „Entwicklung/Veränderung“ → beides (forward + backward)
|
||||
- Ergebnis: Pfad-Kandidaten (nicht nur Nodes)
|
||||
|
||||
4. **Reranking (Antwortrelevanz)**
|
||||
- Score = Semantik + Pfadqualität + Antwortform-Passung
|
||||
|
||||
5. **Antwort-Bausteine (Minimal Explanation Subgraph)**
|
||||
- Merged Top-Pfade zu einem kleinen Subgraph (z.B. 8–12 Nodes)
|
||||
- Pruning nach zentralen Knoten und erklärender Kettenform
|
||||
|
||||
---
|
||||
|
||||
## Spezifikation: Intent → Traversal Mode (Heuristik)
|
||||
|
||||
### Intent-Struktur
|
||||
- `direction`: `backward | forward | both`
|
||||
- `preferred_edges`: Menge Edge-Typen
|
||||
- `target_types`: Menge Node-Typen
|
||||
- `max_hops`: int
|
||||
- `need_explanation_chain`: bool
|
||||
|
||||
### Heuristik (Deutsch)
|
||||
- **Warum / Ursache / Auslöser / wodurch / wie kam es dazu**
|
||||
- direction: backward
|
||||
- preferred_edges: `{caused_by, preceeded_by, derived_from}`
|
||||
- target_types: `{experience, decision, strategy, state}`
|
||||
- max_hops: 2–4
|
||||
- **Was führte zu / Folgen / Auswirkungen / resultierte in**
|
||||
- direction: forward
|
||||
- preferred_edges: `{resulted_in, followed_by, impacts}`
|
||||
- target_types: `{decision, strategy, state, principle}`
|
||||
- max_hops: 2–4
|
||||
- **Entwicklung / Veränderung / Weltbild / Glaubenssatz / Charakter**
|
||||
- direction: both
|
||||
- preferred_edges backward: `{caused_by, derived_from}`
|
||||
- preferred_edges forward: `{resulted_in, impacts}`
|
||||
- target_types: `{principle, state, strategy, decision}`
|
||||
- max_hops: 2–4
|
||||
- need_explanation_chain: true
|
||||
|
||||
---
|
||||
|
||||
## Spezifikation: Traversal (Weighted Multi-Hop)
|
||||
|
||||
### Gewichte (Startwerte)
|
||||
**Edge Weights**
|
||||
- `resulted_in`: 1.00
|
||||
- `caused_by`: 1.00
|
||||
- `derived_from`: 0.90
|
||||
- `source_of`: 0.90
|
||||
- `impacts`: 0.70
|
||||
- `impacted_by`: 0.70
|
||||
- `followed_by`: 0.50
|
||||
- `preceeded_by`: 0.50
|
||||
- `related_to`: 0.25
|
||||
- `part_of/consists_of`: 0.25
|
||||
|
||||
**Node-Type Weights**
|
||||
- `experience`: 1.00
|
||||
- `decision`: 1.00
|
||||
- `strategy`: 0.90
|
||||
- `state`: 0.85
|
||||
- `principle`: 0.85
|
||||
- `insight(hub)`: 0.35
|
||||
- `open_question/hypothesis/white_spot`: 0.00 (Filter)
|
||||
|
||||
**Hop Decay**
|
||||
- `hop_decay(h) = 0.75^h`
|
||||
|
||||
### Traversal-Logik (pseudocode-nah)
|
||||
- Multi-Source-Expansion ab Seeds
|
||||
- Pfade priorisiert nach kumuliertem Pfadscore
|
||||
- `visited` verhindert endlose Wiederholungen
|
||||
|
||||
---
|
||||
|
||||
## Spezifikation: Reranking (Semantik + Kausalität + Antwortform)
|
||||
|
||||
### Final Score
|
||||
- `final_score(path) = alpha*semantic + beta*coherence + gamma*shape_match`
|
||||
|
||||
Startwerte:
|
||||
- `alpha = 0.55` (Semantik)
|
||||
- `beta = 0.30` (Kausal-Kohärenz)
|
||||
- `gamma = 0.15` (Passung zur Frageform)
|
||||
|
||||
**Causal Coherence**
|
||||
- Bonus, wenn Pfad Kausal-Edges enthält (`resulted_in/caused_by/derived_from`)
|
||||
- Malus, wenn nur Navigation/Chronologie enthalten ist
|
||||
- Bonus für Kernform: `experience → decision → (state|strategy|principle)`
|
||||
|
||||
---
|
||||
|
||||
## Output: Minimal Explanation Subgraph (MES)
|
||||
Ziel: nicht eine Liste, sondern ein erklärendes Subgraph-Set.
|
||||
|
||||
**Regeln**
|
||||
- Top-Pfade (z.B. 3–5) mergen
|
||||
- max_nodes: 8–12
|
||||
- Pruning:
|
||||
- Hubs raus, wenn sie nur Navigation sind
|
||||
- Decision/Principle/State bevorzugen (Antwortanker)
|
||||
- Bridge-Nodes behalten (in mehreren Pfaden vorkommend)
|
||||
|
||||
---
|
||||
|
||||
## Authoring-Regeln (Graph-Hygiene) – harte Leitplanken
|
||||
1. Kausalität nur auf atomaren Noten (`experience/decision/state/strategy/principle`)
|
||||
2. Hubs/Indexnoten: primär `related_to/consists_of` (keine „Hub verursacht X“-Kausalität)
|
||||
3. Inverse Edges müssen erzeugbar sein (oder Build-Step erzeugt sie deterministisch)
|
||||
4. Chronologie strikt trennen (`followed_by` ≠ `resulted_in`)
|
||||
5. Prinzipien: `derived_from/based_on` für Herkunft (statt pauschal `caused_by`)
|
||||
6. Leere Links als `open_question` oder TODO ohne Kausal-Edge
|
||||
7. Kanonische Dateinamen: Node-Splitting verhindern
|
||||
|
||||
---
|
||||
|
||||
## Nutzen / Erfolgskriterien
|
||||
- **Bessere Answer Relevance**: Mindnet liefert Knoten mit erklärender Kausalstruktur statt nur thematischer Nähe
|
||||
- **Erklärbarkeit**: Antwort kann mit Pfad(en) begründet werden
|
||||
- **Debuggability**: Fehlantworten lassen sich auf falsche/fehlende Kanten zurückführen
|
||||
- **Authoring-Effizienz**: Assistent verhindert typische Edge-Fehler früh
|
||||
|
||||
---
|
||||
|
||||
## Offene Punkte (für nächste Iteration)
|
||||
- Intent-Taxonomie (8–12 Frageklassen) finalisieren und evaluieren
|
||||
- Welche Edges werden als „kausal“ im engeren Sinne akzeptiert?
|
||||
- Welche Node-Typen sind Pflichtmetadaten für Mindnet?
|
||||
- Evaluation: Retrieval-Qualität mit/ohne Traversal (A/B)
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
# Debug: .env-Lade-Problem in Prod
|
||||
|
||||
**Datum**: 2026-01-12
|
||||
**Version**: v4.5.10
|
||||
**Status**: 🔴 Kritisch
|
||||
|
||||
## Problem
|
||||
|
||||
Möglicherweise wird die `.env`-Datei in Prod nicht korrekt geladen, was zu:
|
||||
- Falschen Log-Levels (DEBUG=true wird ignoriert)
|
||||
- Falschen Collection-Präfixen
|
||||
- Falschen Konfigurationen
|
||||
führen kann.
|
||||
|
||||
## Diagnose
|
||||
|
||||
### Schritt 1: Prüfe, ob .env-Datei existiert
|
||||
|
||||
```bash
|
||||
# In Prod
|
||||
cd ~/mindnet
|
||||
ls -la .env
|
||||
cat .env | head -20
|
||||
```
|
||||
|
||||
### Schritt 2: Prüfe Arbeitsverzeichnis beim Start
|
||||
|
||||
```bash
|
||||
# In Prod - prüfe, von wo uvicorn gestartet wird
|
||||
ps aux | grep uvicorn
|
||||
# Oder in systemd service:
|
||||
cat /etc/systemd/system/mindnet.service | grep WorkingDirectory
|
||||
```
|
||||
|
||||
### Schritt 3: Verifikations-Script ausführen
|
||||
|
||||
```bash
|
||||
# In Prod
|
||||
cd ~/mindnet
|
||||
source .venv/bin/activate
|
||||
python3 scripts/verify_env_loading.py
|
||||
```
|
||||
|
||||
**Erwartete Ausgabe**:
|
||||
```
|
||||
✅ .env geladen von: /path/to/mindnet/.env
|
||||
✅ COLLECTION_PREFIX = mindnet
|
||||
✅ DEBUG = true
|
||||
```
|
||||
|
||||
### Schritt 4: Manuelle Verifikation
|
||||
|
||||
```python
|
||||
# In Python-REPL in Prod
|
||||
import os
|
||||
from pathlib import Path
|
||||
from dotenv import load_dotenv
|
||||
|
||||
# Prüfe aktuelles Verzeichnis
|
||||
print(f"CWD: {Path.cwd()}")
|
||||
print(f"Projekt-Root: {Path(__file__).parent.parent.parent}")
|
||||
|
||||
# Lade .env
|
||||
env_file = Path(".env")
|
||||
if env_file.exists():
|
||||
load_dotenv(env_file, override=True)
|
||||
print(f"✅ .env geladen: {env_file.absolute()}")
|
||||
else:
|
||||
print(f"❌ .env nicht gefunden in: {env_file.absolute()}")
|
||||
|
||||
# Prüfe kritische Variablen
|
||||
print(f"DEBUG: {os.getenv('DEBUG', 'NICHT GESETZT')}")
|
||||
print(f"COLLECTION_PREFIX: {os.getenv('COLLECTION_PREFIX', 'NICHT GESETZT')}")
|
||||
```
|
||||
|
||||
## Mögliche Ursachen
|
||||
|
||||
### 1. Arbeitsverzeichnis-Problem
|
||||
- **Problem**: uvicorn wird aus einem anderen Verzeichnis gestartet
|
||||
- **Lösung**: Expliziter Pfad in `config.py` (bereits implementiert)
|
||||
|
||||
### 2. .env-Datei nicht im Projekt-Root
|
||||
- **Problem**: .env liegt in `config/prod.env` statt `.env`
|
||||
- **Lösung**: Symlink erstellen oder Pfad anpassen
|
||||
|
||||
### 3. Systemd-Service ohne WorkingDirectory
|
||||
- **Problem**: Service startet ohne korrektes Arbeitsverzeichnis
|
||||
- **Lösung**: `WorkingDirectory=/path/to/mindnet` in systemd service
|
||||
|
||||
### 4. Mehrere .env-Dateien
|
||||
- **Problem**: Es gibt `.env`, `prod.env`, `config/prod.env` - welche wird geladen?
|
||||
- **Lösung**: Expliziter Pfad oder Umgebungsvariable `DOTENV_PATH`
|
||||
|
||||
## Fix-Implementierung
|
||||
|
||||
Der Code in `app/config.py` wurde erweitert:
|
||||
- ✅ Expliziter Pfad für `.env` im Projekt-Root
|
||||
- ✅ Fallback auf automatische Suche
|
||||
- ✅ Debug-Logging (wenn verfügbar)
|
||||
|
||||
## Verifikation nach Fix
|
||||
|
||||
1. **Log prüfen**: Sollte `✅ .env geladen von: ...` zeigen
|
||||
2. **Umgebungsvariablen prüfen**: `echo $DEBUG`, `echo $COLLECTION_PREFIX`
|
||||
3. **Settings prüfen**: `python3 -c "from app.config import get_settings; s = get_settings(); print(f'DEBUG: {s.DEBUG}, PREFIX: {s.COLLECTION_PREFIX}')"`
|
||||
@@ -0,0 +1,134 @@
|
||||
# Deployment-Checkliste: Prod vs. Dev Retrieval-Problem
|
||||
|
||||
**Datum**: 2026-01-12
|
||||
**Version**: v4.5.10
|
||||
**Status**: 🔴 Kritisch
|
||||
|
||||
## Problem
|
||||
|
||||
Prod-System findet keine Suchergebnisse, während Dev-System korrekt funktioniert. Identischer Code, identische Daten.
|
||||
|
||||
## Identifizierte Ursachen
|
||||
|
||||
### 1. 🔴 **KRITISCH: Alte EdgeDTO-Version in Prod**
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
ERROR: 1 validation error for EdgeDTO
|
||||
provenance
|
||||
Input should be 'explicit', 'rule', 'smart' or 'structure'
|
||||
[type=literal_error, input_value='explicit:callout', input_type=str]
|
||||
```
|
||||
|
||||
**Ursache**:
|
||||
- Prod verwendet eine **alte Version** des `EdgeDTO`-Modells aus `app/models/dto.py`
|
||||
- Die alte Version unterstützt nur: `"explicit", "rule", "smart", "structure"`
|
||||
- Die neue Version (v4.5.3+) unterstützt: `"explicit:callout", "explicit:wikilink", "explicit:note_zone", ...`
|
||||
|
||||
**Lösung**:
|
||||
- ✅ Code in `dto.py` ist bereits korrekt (Zeile 51-56)
|
||||
- ⚠️ **Prod muss neu gestartet werden**, um die neue Version zu laden
|
||||
- ⚠️ **Python-Modul-Cache leeren** falls nötig: `find . -type d -name __pycache__ -exec rm -r {} +`
|
||||
|
||||
### 2. ✅ Collection-Präfix korrekt
|
||||
|
||||
- Prod: `COLLECTION_PREFIX=mindnet` → `mindnet_chunks` ✅
|
||||
- Dev: `COLLECTION_PREFIX=mindnet_dev` → `mindnet_dev_chunks` ✅
|
||||
- **Kein Problem hier**
|
||||
|
||||
## Sofortmaßnahmen
|
||||
|
||||
### Schritt 1: Code-Verifikation in Prod
|
||||
|
||||
```bash
|
||||
# In Prod-System
|
||||
cd /path/to/mindnet
|
||||
grep -A 10 "provenance.*Literal" app/models/dto.py
|
||||
```
|
||||
|
||||
**Erwartete Ausgabe**:
|
||||
```python
|
||||
provenance: Optional[Literal[
|
||||
"explicit", "rule", "smart", "structure",
|
||||
"explicit:callout", "explicit:wikilink", "explicit:note_zone", ...
|
||||
]] = "explicit"
|
||||
```
|
||||
|
||||
**Falls nicht vorhanden**: Code ist nicht aktualisiert → Deployment erforderlich
|
||||
|
||||
### Schritt 2: Python-Cache leeren
|
||||
|
||||
```bash
|
||||
# In Prod-System
|
||||
find . -type d -name __pycache__ -exec rm -r {} +
|
||||
find . -name "*.pyc" -delete
|
||||
```
|
||||
|
||||
### Schritt 3: Service neu starten
|
||||
|
||||
```bash
|
||||
# FastAPI/uvicorn neu starten
|
||||
# Oder Docker-Container neu starten
|
||||
```
|
||||
|
||||
### Schritt 4: Verifikation
|
||||
|
||||
1. **Test-Query ausführen**:
|
||||
```bash
|
||||
curl -X POST http://localhost:8001/api/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "Was für einen Status hat das Projekt mindnet?"}'
|
||||
```
|
||||
|
||||
2. **Log prüfen**:
|
||||
- ✅ Keine `validation error for EdgeDTO` mehr
|
||||
- ✅ `✨ [SUCCESS] Stream 'facts_stream' lieferte X Treffer.`
|
||||
- ✅ Ergebnisse werden zurückgegeben
|
||||
|
||||
## Code-Vergleich
|
||||
|
||||
### Aktuelle Version (sollte in Prod sein):
|
||||
|
||||
```python
|
||||
# app/models/dto.py (Zeile 51-56)
|
||||
provenance: Optional[Literal[
|
||||
"explicit", "rule", "smart", "structure",
|
||||
"explicit:callout", "explicit:wikilink", "explicit:note_zone", "explicit:note_scope",
|
||||
"inline:rel", "callout:edge", "semantic_ai", "structure:belongs_to", "structure:order",
|
||||
"derived:backlink", "edge_defaults", "global_pool"
|
||||
]] = "explicit"
|
||||
```
|
||||
|
||||
### Alte Version (verursacht Fehler):
|
||||
|
||||
```python
|
||||
# Alte Version (nur 4 Werte)
|
||||
provenance: Optional[Literal[
|
||||
"explicit", "rule", "smart", "structure"
|
||||
]] = "explicit"
|
||||
```
|
||||
|
||||
## Weitere mögliche Ursachen (wenn Fix nicht hilft)
|
||||
|
||||
### 1. Unterschiedliche Python-Versionen
|
||||
- Prüfen: `python --version` in Dev vs. Prod
|
||||
- Pydantic-Verhalten kann zwischen Versionen variieren
|
||||
|
||||
### 2. Unterschiedliche Pydantic-Versionen
|
||||
- Prüfen: `pip list | grep pydantic` in Dev vs. Prod
|
||||
- `requirements.txt` sollte identisch sein
|
||||
|
||||
### 3. Unterschiedliche Embedding-Modelle
|
||||
- Prüfen: `MINDNET_EMBEDDING_MODEL` in beiden Systemen
|
||||
- **Beide verwenden**: `nomic-embed-text` ✅
|
||||
|
||||
### 4. Unterschiedliche Vektor-Dimensionen
|
||||
- Prüfen: `VECTOR_DIM` in beiden Systemen
|
||||
- **Beide verwenden**: `768` ✅
|
||||
|
||||
## Erwartetes Ergebnis nach Fix
|
||||
|
||||
- ✅ Keine Pydantic-Validierungsfehler mehr
|
||||
- ✅ Alle Streams liefern Ergebnisse
|
||||
- ✅ Retrieval funktioniert identisch in Dev und Prod
|
||||
- ✅ `explicit:callout` Provenance wird korrekt akzeptiert
|
||||
@@ -0,0 +1,134 @@
|
||||
# Fix: Python-Modul-Cache-Problem in Prod
|
||||
|
||||
**Datum**: 2026-01-12
|
||||
**Version**: v4.5.10
|
||||
**Status**: 🔴 Kritisch
|
||||
|
||||
## Problem
|
||||
|
||||
Code in `app/models/dto.py` ist korrekt (enthält `explicit:callout`), aber Prod verwendet trotzdem eine alte Version.
|
||||
|
||||
**Symptom**:
|
||||
```
|
||||
ERROR: 1 validation error for EdgeDTO
|
||||
provenance
|
||||
Input should be 'explicit', 'rule', 'smart' or 'structure'
|
||||
[type=literal_error, input_value='explicit:callout', input_type=str]
|
||||
```
|
||||
|
||||
## Ursache
|
||||
|
||||
**Python-Modul-Cache**: Python speichert kompilierte `.pyc` Dateien in `__pycache__` Verzeichnissen. Wenn der Code aktualisiert wird, aber der Service nicht neu gestartet wird, lädt Python die alte gecachte Version.
|
||||
|
||||
## Sofortmaßnahmen
|
||||
|
||||
### Schritt 1: Python-Cache leeren
|
||||
|
||||
```bash
|
||||
# In Prod-System
|
||||
cd ~/mindnet
|
||||
|
||||
# Finde und lösche alle __pycache__ Verzeichnisse
|
||||
find . -type d -name __pycache__ -exec rm -r {} + 2>/dev/null || true
|
||||
|
||||
# Finde und lösche alle .pyc Dateien
|
||||
find . -name "*.pyc" -delete
|
||||
|
||||
# Speziell für dto.py
|
||||
rm -rf app/models/__pycache__
|
||||
rm -rf app/__pycache__
|
||||
rm -rf __pycache__
|
||||
```
|
||||
|
||||
### Schritt 2: Verifikation des Codes
|
||||
|
||||
```bash
|
||||
# Prüfe, ob der Code korrekt ist
|
||||
grep -A 10 "provenance.*Literal" app/models/dto.py | grep "explicit:callout"
|
||||
```
|
||||
|
||||
**Erwartete Ausgabe**: Sollte `explicit:callout` enthalten
|
||||
|
||||
### Schritt 3: Service neu starten
|
||||
|
||||
**Option A: FastAPI/uvicorn direkt**:
|
||||
```bash
|
||||
# Service stoppen (Ctrl+C oder kill)
|
||||
# Dann neu starten
|
||||
source .venv/bin/activate
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
|
||||
```
|
||||
|
||||
**Option B: Systemd-Service**:
|
||||
```bash
|
||||
sudo systemctl restart mindnet-prod
|
||||
# oder
|
||||
sudo systemctl restart mindnet
|
||||
```
|
||||
|
||||
**Option C: Docker-Container**:
|
||||
```bash
|
||||
docker-compose restart mindnet
|
||||
# oder
|
||||
docker restart mindnet-container
|
||||
```
|
||||
|
||||
### Schritt 4: Verifikation zur Laufzeit
|
||||
|
||||
**Test-Script ausführen** (wenn verfügbar):
|
||||
```bash
|
||||
python3 scripts/verify_dto_import.py
|
||||
```
|
||||
|
||||
**Erwartete Ausgabe**:
|
||||
```
|
||||
✅ EdgeDTO unterstützt 'explicit:callout'
|
||||
✅ 'explicit:callout' ist in der Literal-Liste enthalten
|
||||
✅ EdgeDTO mit 'explicit:callout' erfolgreich erstellt!
|
||||
```
|
||||
|
||||
**Oder manuell testen**:
|
||||
```python
|
||||
python3 -c "
|
||||
from app.models.dto import EdgeDTO
|
||||
test = EdgeDTO(
|
||||
id='test', kind='test', source='test', target='test',
|
||||
weight=1.0, provenance='explicit:callout'
|
||||
)
|
||||
print('✅ EdgeDTO mit explicit:callout funktioniert!')
|
||||
"
|
||||
```
|
||||
|
||||
## Code-Fix (Fallback-Mechanismus)
|
||||
|
||||
Ein Fallback-Mechanismus wurde in `retriever.py` implementiert:
|
||||
- Wenn `EdgeDTO` mit `explicit:callout` fehlschlägt, wird automatisch `explicit` als Fallback verwendet
|
||||
- Dies verhindert, dass der gesamte Retrieval-Prozess fehlschlägt
|
||||
- **WICHTIG**: Dies ist nur eine temporäre Lösung - der Cache muss trotzdem geleert werden!
|
||||
|
||||
## Verifikation nach Fix
|
||||
|
||||
1. **Test-Query ausführen**:
|
||||
```bash
|
||||
curl -X POST http://localhost:8001/api/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "Was für einen Status hat das Projekt mindnet?"}'
|
||||
```
|
||||
|
||||
2. **Log prüfen**:
|
||||
- ✅ Keine `validation error for EdgeDTO` mehr
|
||||
- ✅ Keine `⚠️ [EDGE-DTO] Provenance 'explicit:callout' nicht unterstützt` Warnungen
|
||||
- ✅ `✨ [SUCCESS] Stream 'facts_stream' lieferte X Treffer.`
|
||||
- ✅ Ergebnisse werden zurückgegeben
|
||||
|
||||
## Warum passiert das?
|
||||
|
||||
1. **Code wurde aktualisiert**, aber Service läuft noch mit alter Version im Speicher
|
||||
2. **Python lädt Module nur einmal** - nach dem ersten Import wird die gecachte Version verwendet
|
||||
3. **__pycache__ Verzeichnisse** enthalten kompilierte Bytecode-Versionen der alten Dateien
|
||||
|
||||
## Prävention
|
||||
|
||||
- **Immer Service neu starten** nach Code-Änderungen
|
||||
- **Cache regelmäßig leeren** bei Deployment
|
||||
- **Verwende `--reload` Flag** bei uvicorn für automatisches Neuladen (nur für Dev!)
|
||||
@@ -0,0 +1,163 @@
|
||||
# Analyse: Retrieval-Unterschiede zwischen Dev und Prod
|
||||
|
||||
**Datum**: 2026-01-12
|
||||
**Version**: v4.5.10
|
||||
**Status**: 🔴 Kritisch
|
||||
|
||||
## Problemstellung
|
||||
|
||||
Bei identischer Codebasis und identischen Daten liefert das Dev-System Suchergebnisse, während das Prod-System keine Ergebnisse findet.
|
||||
|
||||
## Identifizierte Ursachen
|
||||
|
||||
### 1. 🔴 **KRITISCH: Inkonsistente Collection-Präfix-Konfiguration**
|
||||
|
||||
**Problem**: Zwei verschiedene Umgebungsvariablen werden für den Collection-Präfix verwendet:
|
||||
|
||||
1. **`app/config.py` (Zeile 24)**:
|
||||
```python
|
||||
COLLECTION_PREFIX: str = os.getenv("MINDNET_PREFIX", "mindnet_dev")
|
||||
```
|
||||
- Verwendet `MINDNET_PREFIX` als Umgebungsvariable
|
||||
- Default: `"mindnet_dev"`
|
||||
|
||||
2. **`app/core/database/qdrant.py` (Zeile 47)**:
|
||||
```python
|
||||
prefix = os.getenv("COLLECTION_PREFIX") or "mindnet"
|
||||
```
|
||||
- Verwendet `COLLECTION_PREFIX` als Umgebungsvariable
|
||||
- Default: `"mindnet"`
|
||||
|
||||
**Auswirkung**:
|
||||
- **Retriever verwendet `QdrantConfig.from_env()`**, das `COLLECTION_PREFIX` liest
|
||||
- **Ingestion verwendet `Settings.COLLECTION_PREFIX`**, das `MINDNET_PREFIX` liest
|
||||
- **Resultat**: Daten werden in verschiedene Collections geschrieben/gesucht:
|
||||
- Dev: `mindnet_dev_chunks`, `mindnet_dev_notes`, `mindnet_dev_edges`
|
||||
- Prod: `mindnet_chunks`, `mindnet_notes`, `mindnet_edges`
|
||||
|
||||
### 2. ⚠️ **Mögliche weitere Ursachen**
|
||||
|
||||
#### 2.1 Unterschiedliche Embedding-Modelle
|
||||
- **Prüfen**: `MINDNET_EMBEDDING_MODEL` in Dev vs. Prod
|
||||
- **Auswirkung**: Unterschiedliche Vektoren → unterschiedliche Similarity-Scores
|
||||
|
||||
#### 2.2 Unterschiedliche Vektor-Dimensionen
|
||||
- **Prüfen**: `VECTOR_DIM` in Dev vs. Prod
|
||||
- **Auswirkung**: Dimension-Mismatch → Suche schlägt fehl
|
||||
|
||||
#### 2.3 Unterschiedliche Qdrant-Instanzen
|
||||
- **Prüfen**: `QDRANT_URL` / `QDRANT_HOST` in Dev vs. Prod
|
||||
- **Auswirkung**: Daten liegen in verschiedenen Datenbanken
|
||||
|
||||
#### 2.4 Unterschiedliche Score-Thresholds
|
||||
- **Prüfen**: Filter-Logik oder Mindest-Scores
|
||||
- **Auswirkung**: Ergebnisse werden gefiltert, bevor sie zurückgegeben werden
|
||||
|
||||
## Diagnose-Checkliste
|
||||
|
||||
### ✅ Sofort prüfen:
|
||||
|
||||
1. **Collection-Präfix-Verifikation**:
|
||||
```bash
|
||||
# Dev
|
||||
echo $COLLECTION_PREFIX
|
||||
echo $MINDNET_PREFIX
|
||||
|
||||
# Prod
|
||||
echo $COLLECTION_PREFIX
|
||||
echo $MINDNET_PREFIX
|
||||
```
|
||||
|
||||
2. **Qdrant Collections prüfen**:
|
||||
```python
|
||||
# In beiden Systemen ausführen
|
||||
from app.core.database.qdrant import get_client, QdrantConfig
|
||||
cfg = QdrantConfig.from_env()
|
||||
client = get_client(cfg)
|
||||
print(f"Prefix: {cfg.prefix}")
|
||||
print(f"Collections: {client.get_collections().collections}")
|
||||
```
|
||||
|
||||
3. **Embedding-Modell prüfen**:
|
||||
```bash
|
||||
# Dev
|
||||
echo $MINDNET_EMBEDDING_MODEL
|
||||
echo $VECTOR_DIM
|
||||
|
||||
# Prod
|
||||
echo $MINDNET_EMBEDDING_MODEL
|
||||
echo $VECTOR_DIM
|
||||
```
|
||||
|
||||
4. **Qdrant-Verbindung prüfen**:
|
||||
```bash
|
||||
# Dev
|
||||
echo $QDRANT_URL
|
||||
echo $QDRANT_HOST
|
||||
echo $QDRANT_PORT
|
||||
|
||||
# Prod
|
||||
echo $QDRANT_URL
|
||||
echo $QDRANT_HOST
|
||||
echo $QDRANT_PORT
|
||||
```
|
||||
|
||||
## Lösungsvorschläge
|
||||
|
||||
### Option 1: Harmonisierung der Umgebungsvariablen (Empfohlen)
|
||||
|
||||
**Ziel**: Eine einzige Umgebungsvariable für den Collection-Präfix verwenden.
|
||||
|
||||
**Änderungen**:
|
||||
1. **`app/core/database/qdrant.py`**:
|
||||
```python
|
||||
prefix = os.getenv("COLLECTION_PREFIX") or os.getenv("MINDNET_PREFIX") or "mindnet"
|
||||
```
|
||||
- Unterstützt beide Variablen (Abwärtskompatibilität)
|
||||
- `COLLECTION_PREFIX` hat Priorität
|
||||
|
||||
2. **`app/config.py`**:
|
||||
```python
|
||||
COLLECTION_PREFIX: str = os.getenv("COLLECTION_PREFIX") or os.getenv("MINDNET_PREFIX") or "mindnet_dev"
|
||||
```
|
||||
- Unterstützt beide Variablen
|
||||
- `COLLECTION_PREFIX` hat Priorität
|
||||
|
||||
3. **Dokumentation**: Klarstellen, dass `COLLECTION_PREFIX` die primäre Variable ist
|
||||
|
||||
### Option 2: Explizite Konfiguration in .env
|
||||
|
||||
**Ziel**: Beide Systeme verwenden explizit gesetzte `COLLECTION_PREFIX` Werte.
|
||||
|
||||
**Dev `.env`**:
|
||||
```env
|
||||
COLLECTION_PREFIX=mindnet_dev
|
||||
```
|
||||
|
||||
**Prod `.env`**:
|
||||
```env
|
||||
COLLECTION_PREFIX=mindnet
|
||||
```
|
||||
|
||||
### Option 3: Daten-Migration
|
||||
|
||||
**Ziel**: Daten von einer Collection in die andere migrieren.
|
||||
|
||||
**Vorgehen**:
|
||||
1. Identifizieren, welche Collection die "richtigen" Daten enthält
|
||||
2. Daten von Dev nach Prod migrieren (oder umgekehrt)
|
||||
3. Collection-Präfix harmonisieren
|
||||
|
||||
## Sofortmaßnahmen
|
||||
|
||||
1. ✅ **Prüfen**: Welche Collections existieren in beiden Systemen?
|
||||
2. ✅ **Prüfen**: Welche Umgebungsvariablen sind gesetzt?
|
||||
3. ✅ **Prüfen**: Welche Collection enthält die Daten?
|
||||
4. ✅ **Fix**: Collection-Präfix-Konfiguration harmonisieren
|
||||
5. ✅ **Test**: Retrieval in beiden Systemen verifizieren
|
||||
|
||||
## Erwartetes Ergebnis nach Fix
|
||||
|
||||
- ✅ Beide Systeme verwenden dieselbe Collection-Präfix-Logik
|
||||
- ✅ Retrieval findet Daten in beiden Systemen
|
||||
- ✅ Konsistente Konfiguration zwischen Ingestion und Retrieval
|
||||
@@ -0,0 +1,207 @@
|
||||
---
|
||||
doc_type: operations_manual
|
||||
audience: devops, deployment_engineer
|
||||
scope: docker, compose, container_security, nas_mount
|
||||
status: draft
|
||||
version: 0.3.0
|
||||
context: "Container-Betrieb von Mindnet (Dev/Prod) auf llm-node. Vorbereitung, noch keine produktive Umschaltung."
|
||||
---
|
||||
|
||||
# Container-Betrieb (Docker Compose)
|
||||
|
||||
Stand: 28.10.2026. **Status: Dev aktiv (Push auf `develop`), Prod vorbereitet, nicht aktiv.** Produktion läuft unverändert über systemd und `.gitea/workflows/deploy.yml` (siehe [Deployment Guide](04_deployment_guide.md)). Der Containerstand basiert auf dem stabilen `main`-Verhalten **ohne** Privacy Gateway.
|
||||
|
||||
**Grundsatz: 1:1-Migration.** Der Container betreibt dieselbe Anwendung mit derselben Konfiguration wie die jeweilige systemd-Instanz, damit beide parallel verglichen werden können. Er liest deren `.env` unverändert. Konfigurationsänderungen sind nachgelagerte Schritte.
|
||||
|
||||
## 1. Überblick
|
||||
|
||||
| | Dev | Prod |
|
||||
| --- | --- | --- |
|
||||
| Vergleichsinstanz (systemd) | 8002/8502, `/home/llmadmin/mindnet_dev` | 8001/8501, `/home/llmadmin/mindnet` |
|
||||
| Anwendungskonfiguration | `/home/llmadmin/mindnet_dev/.env`, unverändert | `/home/llmadmin/mindnet/.env`, unverändert |
|
||||
| Container-Angaben | `/home/llmadmin/docker/mindnet-dev/container.env` | `/home/llmadmin/docker/mindnet/container.env` |
|
||||
| Compose-Datei / Projekt | `deploy/compose.dev.yml` / `mindnet-dev` | `deploy/compose.prod.yml` / `mindnet-prod` |
|
||||
| API (Standard nur `127.0.0.1`) | 8012 | 8011 |
|
||||
| UI (Standard `0.0.0.0`, wie systemd) | 8512 | 8511 |
|
||||
| Qdrant, Ollama | gemeinsame Host-Dienste, wie systemd | gemeinsame Host-Dienste, wie systemd |
|
||||
| Präfix, Vault | aus der `.env` der systemd-Instanz | aus der `.env` der systemd-Instanz |
|
||||
|
||||
Die Ports kollidieren weder untereinander noch mit systemd (8001/8002/8501/8502), damit Container und systemd parallel laufen und verglichen werden können.
|
||||
|
||||
**Abweichungen vom heutigen Verhalten, bewusst und nur diese:**
|
||||
|
||||
- **Adressen der Host-Dienste:** `QDRANT_URL` und `MINDNET_OLLAMA_URL` zeigen auf `host.docker.internal`. `127.0.0.1` wäre im Container der Container selbst. Ziel sind dieselben Dienste.
|
||||
- **Vault nur lesend:** Zwei Instanzen sollen nicht parallel in denselben Vault schreiben. Außerdem ist R2 offen. Speichern aus der Container-UI schlägt deshalb fehl, lesen und suchen funktionieren.
|
||||
- **Cloud-Keys:** Enthält die `.env` Cloud-Keys, startet der Container nur, wenn in der Container-Datei `MINDNET_ALLOW_CLOUD_EGRESS=true` steht. Mit `true` verhält er sich wie heute; die Entscheidung trifft der Betreiber.
|
||||
- **Bind-Adresse der API:** Standard ist `127.0.0.1`; über `MINDNET_API_BIND` lässt sie sich wie bei systemd auf `0.0.0.0` setzen.
|
||||
|
||||
Alle Dateien liegen unter `deploy/`. Dieser Ordner gehört nicht zu `DEPLOY_DIRS` des bestehenden Workflows und wird daher nicht automatisch auf den Server synchronisiert. Der alte Ordner `docker/` (MiniLM-Embed-Dienst, Port 8990) bleibt unverändert, siehe Abschnitt 9.
|
||||
|
||||
## 2. Image
|
||||
|
||||
`deploy/Dockerfile`, Build-Kontext ist das Repository-Root:
|
||||
|
||||
```bash
|
||||
docker build -f deploy/Dockerfile -t mindnet:$(git rev-parse --short HEAD) .
|
||||
```
|
||||
|
||||
- **Ein Image, drei Modi:** `api` (uvicorn, 1 Worker), `ui` (Streamlit), `preflight [--live]`.
|
||||
- **Reproduzierbar:** Basis `python:3.12-slim-bookworm` per Digest; Abhängigkeiten aus `deploy/requirements.lock` mit `--require-hashes`.
|
||||
- **Ohne torch/sentence-transformers:** Der MiniLM-Pfad (`app/embeddings.py`, `embed_router`) ist im Laufzeitcode nicht eingebunden. Embeddings kommen ausschließlich von Ollama.
|
||||
- **Nicht-root:** Nutzer `mindnet` (UID 10001). Code und Config gehören root und sind nur lesbar.
|
||||
- **Build-Kontext als Allowlist** (`/.dockerignore`): Nur `app/`, `config/`, `scripts/`, `tests/` und `deploy/` gelangen in den Build-Kontext. Ausgeschlossen bleiben `.env`-Dateien, `config/*.env`, Vault, Logs und venvs.
|
||||
- **Test-Target:** `docker build --target test …` installiert zusätzlich pytest.
|
||||
|
||||
### Lock neu erzeugen
|
||||
|
||||
Nur bewusst, z. B. bei Sicherheitsupdates, und danach die Testsuite laufen lassen:
|
||||
|
||||
```bash
|
||||
cd deploy
|
||||
uv pip compile requirements.in --universal --python-version 3.12 \
|
||||
--exclude-newer <ISO-Datum> --generate-hashes --no-header -o requirements.lock
|
||||
uv pip compile requirements-test.in --universal --python-version 3.12 \
|
||||
--exclude-newer <ISO-Datum> --generate-hashes --no-header -o requirements-test.lock
|
||||
```
|
||||
|
||||
Der aktuelle Lock wurde mit `--exclude-newer 2026-01-22` erzeugt, also dem Stand nach dem letzten `main`-Commit, den das systemd-Deploy damals per `pip install` gezogen haben dürfte. **Offen:** Abgleich mit `pip freeze` der produktiven venv auf llm-node (nur lesend, erfordert Freigabe).
|
||||
|
||||
## 3. Preflight (Abbruch statt stiller Fehler)
|
||||
|
||||
`deploy/entrypoint.py` prüft vor jedem Start und bricht mit Exit-Code 1 ab, wenn:
|
||||
|
||||
| Prüfung | Schützt vor |
|
||||
| --- | --- |
|
||||
| `MINDNET_ENV` ∈ {dev, prod}; `COLLECTION_PREFIX` explizit; Dev nur `*_dev`, Prod nie `*_dev` | Dev schreibt in Prod-Collections; stiller Default `mindnet` |
|
||||
| `VECTOR_DIM == 768`, Profil `embedding_expert` = ollama/`nomic-embed-text`/768, kein abweichendes `MINDNET_EMBEDDING_MODEL` | stiller Rückfall auf 384 (MiniLM) in `qdrant.py` bzw. auf das Chat-Modell als Embedding |
|
||||
| Cloud-Key gesetzt ohne `MINDNET_ALLOW_CLOUD_EGRESS=true` | unmaskierte Vault-Inhalte an OpenRouter/Gemini |
|
||||
| Vault fehlt, leer oder nicht lesbar, optionaler Sentinel fehlt, Mount nicht `ro` (`statvfs` `ST_RDONLY`) | Arbeiten auf leerem NAS-Mountpunkt; Schreiben in den Vault (R2) |
|
||||
| `MINDNET_OLLAMA_URL`/`QDRANT_URL` fehlen oder zeigen auf `localhost`/`127.0.0.1` | App fiele still auf `127.0.0.1` zurück, im Container also auf sich selbst |
|
||||
|
||||
Umgebung, Dimension, Schreibschutz und die Adressen der Host-Dienste stehen in den Compose-Dateien unter `environment` und haben Vorrang vor beiden env-Dateien. Präfix und Vault-Pfad kommen aus der `.env` der systemd-Instanz. Die Präfix-Regel gilt trotzdem: Dev nur `*_dev`, Prod nie.
|
||||
|
||||
`preflight --live` prüft zusätzlich **nur lesend** aus dem Container heraus, also über dasselbe Netz wie die API:
|
||||
|
||||
| Prüfung | Fehlerbild bei Abbruch |
|
||||
| --- | --- |
|
||||
| Ollama `/api/tags` erreichbar | `… nicht erreichbar`; bei `host.docker.internal` mit Hinweis auf eine `127.0.0.1`-Bindung |
|
||||
| Alle Ollama-Modelle vorhanden: Profile mit `provider: ollama` (heute `nomic-embed-text`, `phi3:mini`) plus `MINDNET_LLM_MODEL` | `Ollama fehlen die Modelle: …` |
|
||||
| Ollama liefert für `nomic-embed-text` 768 Dimensionen | `Ollama liefert N Dimensionen` |
|
||||
| Qdrant `/collections` erreichbar (mit `QDRANT_API_KEY`, falls gesetzt) | `nicht erreichbar` bzw. `HTTP 401` |
|
||||
| `<prefix>_notes`/`<prefix>_chunks` haben 768 Dimensionen; fehlende Collections sind erlaubt (Hinweis) | `Collection … hat Dimension …` |
|
||||
|
||||
Netzwerkfehler enden als klarer Abbruch mit Exit-Code 1, nicht als Traceback.
|
||||
|
||||
```bash
|
||||
docker compose -f deploy/compose.dev.yml --env-file "$MINDNET_ENV_FILE" run --rm --no-deps api preflight --live # Variablen wie in Abschnitt 7
|
||||
```
|
||||
|
||||
## 4. Vault auf dem NAS
|
||||
|
||||
- **Gleicher Vault wie systemd:** `deploy/appenv.py` liest `MINDNET_VAULT_ROOT` aus der `.env`. Ein relativer Pfad wird wie bei systemd gegen das `WorkingDirectory` (Ordner der `.env`) aufgelöst und im Container unter `/app/<pfad>` eingehängt, ein absoluter Pfad 1:1. Dadurch zeigt derselbe Wert im Container auf dasselbe Verzeichnis. Fehlt der Wert, gilt der App-Default `./vault_master`.
|
||||
- Der Bind-Mount ist `read_only: true`, mit `create_host_path: false` (kein stilles Anlegen) und `propagation: rslave`. Ein später wieder eingehängtes NAS wird dadurch im Container sichtbar, sofern der Host-Mountpunkt `shared` ist.
|
||||
- **Sentinel:** Standardmäßig wird nur geprüft, dass der Vault lesbar und nicht leer ist; einen bestimmten Aufbau verlangt der Container nicht (wie systemd). Optional kann `MINDNET_VAULT_SENTINEL` in der Container-Datei eine Datei relativ zum Vault vorschreiben, z. B. `_system/dictionary/edge_vocabulary.md` für den NAS-Vault.
|
||||
- **NAS beim Start nicht verfügbar:** Die API startet nicht. `restart: unless-stopped` versucht es mit Backoff weiter. Die UI hängt an der gesunden API.
|
||||
- **NAS fällt im Betrieb aus:** Der Healthcheck meldet die API als `unhealthy`. Lesende Abfragen gegen Qdrant laufen weiter. Speichern ist wegen des schreibgeschützten Mounts ohnehin ausgeschlossen. `/ingest/save` würde ohne `ro` den fehlenden Vault-Ordner per `os.makedirs` neu anlegen; genau das verhindert der Mount.
|
||||
- **Berechtigungen:** Der Container läuft als UID 10001. Der Vault muss für diese UID **lesbar** sein, z. B. über `others: r-x` oder eine passende Gruppe auf dem NAS-Export. Bei CIFS-Mounts gelten `uid`/`gid`/`file_mode` aus den Mount-Optionen des Hosts. Prüfen, ohne am NAS etwas zu ändern:
|
||||
|
||||
```bash
|
||||
mountpoint <vault-pfad>; findmnt -o TARGET,SOURCE,FSTYPE,OPTIONS,PROPAGATION <vault-pfad>
|
||||
sudo -u '#10001' test -r <vault-pfad>/_system/dictionary/edge_vocabulary.md && echo lesbar
|
||||
```
|
||||
|
||||
## 5. Netzwerk und gemeinsame Dienste
|
||||
|
||||
Die Container erreichen Host-Dienste über `host.docker.internal` (`host-gateway`). **Voraussetzung, vor dem ersten Start auf llm-node nur lesend zu prüfen:**
|
||||
|
||||
```bash
|
||||
ss -ltnp | grep -E ':(6333|11434)\b' # Binden Qdrant/Ollama nur an 127.0.0.1?
|
||||
docker inspect qdrant --format '{{json .HostConfig.PortBindings}}'
|
||||
```
|
||||
|
||||
Sind Qdrant oder Ollama nur an `127.0.0.1` gebunden, ist der Host-Gateway nicht erreichbar. Lösungsmöglichkeiten, jede nur mit Freigabe: Ollama an die Bridge-Adresse binden (`OLLAMA_HOST`), den Prod-Container an das bestehende Docker-Netz von `qdrant` anhängen (externes Netz), oder `network_mode: host` für die API. Keine davon ist umgesetzt.
|
||||
|
||||
Ollama ist seit dem 28.10.2026 für die Docker-Netze freigegeben: `OLLAMA_HOST=0.0.0.0:11434` und `ufw allow from 172.16.0.0/12 to any port 11434`, das LAN bleibt gesperrt. Die Prod-Qdrant ist über ihren veröffentlichten Port 6333 erreichbar.
|
||||
|
||||
Die API hat keine Authentisierung und wird standardmäßig nur an `127.0.0.1` veröffentlicht. Die UI erreicht sie intern über `http://api:8000`. Die UI ist wie bei systemd im LAN erreichbar (`MINDNET_UI_BIND=0.0.0.0`).
|
||||
|
||||
## 6. Härtung
|
||||
|
||||
Für `api` und `ui`: `read_only`-Rootfs, `tmpfs /tmp`, `cap_drop: ALL`, `no-new-privileges`, `init`, `pids_limit`, `mem_limit`, rotierende json-Logs. Beschreibbar sind nur die Volumes `logs` (`/app/logs`) und `data` (`/app/data`). Die UI bindet `data` nur lesend ein.
|
||||
|
||||
## 7. Bedienung
|
||||
|
||||
Normalerweise über das Deploy-Skript (Abschnitt 8), auch manuell:
|
||||
|
||||
```bash
|
||||
export MINDNET_APP_ENV_FILE=/home/llmadmin/mindnet_dev/.env # systemd-Dev, unverändert
|
||||
export MINDNET_ENV_FILE=/home/llmadmin/docker/mindnet-dev/container.env # aus deploy/env/dev.env.example
|
||||
deploy/deploy.sh dev
|
||||
```
|
||||
|
||||
Für Einzelschritte von Hand braucht Compose zusätzlich die abgeleiteten Vault-Werte:
|
||||
|
||||
```bash
|
||||
eval "$(python3 deploy/appenv.py "$MINDNET_APP_ENV_FILE" "$MINDNET_ENV_FILE")"
|
||||
export MINDNET_VAULT_HOST_PATH MINDNET_VAULT_TARGET MINDNET_IMAGE_TAG=dev-manual
|
||||
docker compose -f deploy/compose.dev.yml --env-file "$MINDNET_ENV_FILE" up -d --wait
|
||||
```
|
||||
|
||||
Einen Import startet der Container-Workflow nicht; die Daten sind dieselben wie bei systemd.
|
||||
|
||||
**Ohne Cloud-Keys** (Prod-Standard) ruft der stabile Code für Cloud-Profile Ollama mit der Cloud-Modell-ID auf. Das scheitert zunächst und endet über `fallback_profile` bei `identity_safe` (phi3:mini). Chat funktioniert damit lokal, aber mit Verzögerung durch Fehlversuche (Review R4).
|
||||
|
||||
## 8. Gitea-Pipeline: `develop` → Dev, `main` → Prod
|
||||
|
||||
Gleiches Muster wie Kansho, aber auf dem eigenen Runner des Zielhosts (heute llm-node, Label `linux_host`, läuft als `llmadmin`, nicht wie im [Server-Handbuch](04_server_operation_manual.md) angegeben als `root`). Gitea führt nur `.gitea/workflows/` aus:
|
||||
|
||||
| Workflow | Trigger | Status |
|
||||
| --- | --- | --- |
|
||||
| `.gitea/workflows/deploy-dev.yml` | Push `develop`, manuell | **aktiv** (G3) |
|
||||
| `deploy/gitea-workflows/deploy-prod.yml` | Push `main`, manuell | Vorlage. Aktivierung bei G5, im **selben Commit** `git rm .gitea/workflows/deploy.yml` (systemd), sonst deployen beide |
|
||||
|
||||
Fehlt die Container-Datei, legt der Workflow sie beim ersten Lauf aus `deploy/env/<env>.env.example` an. Sie enthält nur Ports, Bind-Adressen und Freigaben. Eine vorhandene Datei wird nie überschrieben. `deploy/appenv.py` bricht ab, wenn darin Anwendungswerte stehen, damit sie die `.env` der systemd-Instanz nicht überschreiben kann.
|
||||
|
||||
Prod nur über einen Merge-Commit `develop` → `main` (`git merge --no-ff develop`), wie bei Kansho.
|
||||
|
||||
Beide Workflows rufen nur `deploy/deploy.sh dev|prod` auf. Jeder Schritt bricht ab, **bevor** der laufende Stack angefasst wird:
|
||||
|
||||
1. Container-Tests im Test-Image mit `--network none` (Preflight, Erreichbarkeit gegen Fake-Server, statische Compose-/Workflow-Prüfungen), **blockierend**.
|
||||
2. Volle Testsuite mit `--network none`, **informativ**, bis die 17 bekannten Fehler behoben sind ([Migrationsplan §4](../05_Development/05_docker_migration_plan.md)). Ohne Netzwerk kann kein Test einen echten Dienst erreichen.
|
||||
3. Image bauen, Tag `<env>-<commit>`.
|
||||
4. Vault und Präfix aus der systemd-`.env` ableiten (`deploy/appenv.py`), danach `preflight --live` in einem Wegwerf-Container.
|
||||
5. `up -d --wait` (Healthchecks) und danach `deploy/smoke.py` über die veröffentlichten Ports, also aus Sicht des Hosts:
|
||||
- API `/healthz`: Status `ok`, erwartetes Präfix.
|
||||
- API `/admin/stats`: Vektorgröße 768; die API erreicht Qdrant (Collection-Counts ≠ −1).
|
||||
- UI `/_stcore/health`.
|
||||
- `--require-data`: alle Collections lesbar, Notes nicht leer, denn die Daten der systemd-Instanz sind vorhanden.
|
||||
6. Erfolg: Der Tag wird in `last_good_tag` neben der Container-Datei vermerkt. Verwaiste Container früherer Stände entfernt `--remove-orphans`. Prod bei Fehler: Rückkehr zum letzten erfolgreichen Tag und erneuter Smoke-Test; der Workflow bleibt trotzdem rot.
|
||||
|
||||
Beide env-Dateien liegen nur auf dem Host (Tabelle in Abschnitt 1). Compose liest sie direkt über `MINDNET_APP_ENV_FILE` und `MINDNET_ENV_FILE`; Secrets landen nicht im Runner-Workspace.
|
||||
|
||||
**Unterschiede zu Kansho, bewusst:**
|
||||
|
||||
| | Kansho | Mindnet |
|
||||
| --- | --- | --- |
|
||||
| Checkout | `git clone`/`reset --hard` im Zielordner | `git fetch` genau des Push-Commits vom eigenen Gitea in den Runner-Workspace, mit Job-Token (auch bei privatem Repo). Keine externen Actions, also kein Zugriff auf github.com nötig. Compose-Projektnamen sind fest, daher ist der Ordner egal |
|
||||
| Tests | eigener `test.yml` nach dem Dev-Deploy | Teil des Deploys, **vor** dem Start; ohne Netzwerk |
|
||||
| Prüfung vor Start | keine | `preflight --live` (Dienste, Modelle, Dimensionen, Vault) |
|
||||
| Image | `build --no-cache`, kein Tag | Hash-Lock, Tag pro Commit, Rollback in Prod |
|
||||
| Zustand des Hosts | `.env` im Checkout | env-Datei und `last_good_tag` außerhalb des Checkouts |
|
||||
|
||||
**Umzug auf einen anderen Mini-PC:** Runner dort registrieren, in beiden Workflows `runs-on`, `MINDNET_APP_ENV_FILE` und `MINDNET_ENV_FILE` anpassen. Hostspezifisch ist sonst nur `host.docker.internal` (über `host-gateway`, funktioniert auf jedem Linux-Docker).
|
||||
|
||||
## 9. Altbestand `docker/` (MiniLM)
|
||||
|
||||
`docker/docker-compose.yml` und `docker/embeddings.Dockerfile` bauen einen MiniLM-Dienst (384 Dimensionen, Port 8990). Laut [Server-Handbuch](04_server_operation_manual.md) läuft `mindnet-embed` auf llm-node. Im Anwendungscode wird er nicht genutzt; außerdem verweist das Dockerfile auf `app/embed_server.py`, das im Repository nicht mehr existiert. **Nicht entfernen, bevor geprüft ist**, ob der Container auf llm-node noch läuft und von irgendetwas angesprochen wird. Grund: `deploy.yml` synchronisiert `docker/` mit `rsync --delete`; eine Löschung auf `main` entfernt die Dateien auch auf dem Server.
|
||||
|
||||
## 10. Noch nicht verifiziert
|
||||
|
||||
- Kein `docker build` und kein Compose-Start: Auf der Entwicklungsmaschine ist kein Docker installiert. Verifiziert sind:
|
||||
- die Preflight-Logik und die Erreichbarkeitsprüfungen gegen einen Fake-Server (`tests/test_container_connectivity.py`),
|
||||
- statische Compose-, Dockerfile- und Workflow-Zusagen (`tests/test_container_preflight.py`),
|
||||
- der Ablauf von `deploy.sh` mit einer Docker-Attrappe: Erfolg, Abbruch im Preflight vor dem Start, Prod-Startfehler mit Rollback,
|
||||
- die Testsuite mit exakt den gelockten Versionen (frische venv aus dem Lock, Windows).
|
||||
- Runner auf llm-node: Docker-Compose-Version (benötigt `up --wait` und Interpolation in `env_file`), Rechte des Runner-Nutzers auf `/home/llmadmin/docker/`.
|
||||
- Healthcheck von `qdrant/qdrant` nutzt `bash` und `/dev/tcp`; beim ersten Dev-Build prüfen.
|
||||
- Der Abgleich mit den produktiven Paketversionen fehlt (Abschnitt 2).
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
doc_type: development_plan
|
||||
audience: developer, devops
|
||||
scope: docker_migration, release_gates, test_baseline, privacy_gateway
|
||||
status: draft
|
||||
version: 0.1.0
|
||||
context: "Migrationsplan Mindnet → Container (Dev/Prod) mit Freigabe-Gates, Testbaseline und Anforderungen an das Privacy Gateway."
|
||||
---
|
||||
|
||||
# Migrationsplan: Containerisierung
|
||||
|
||||
Stand: 28.10.2026. Betriebsdetails: [Container-Betrieb](../04_Operations/04_docker_deployment.md). Die Review-Befunde R1–R9 stehen in `05_review_2026-09-25.md` auf dem Branch `codex/privacy-gateway`. Der Link funktioniert erst, wenn beide Stände in `develop` zusammengeführt sind.
|
||||
|
||||
## 1. Rahmenbedingungen (entschieden)
|
||||
|
||||
- Ziel-Host bleibt vorerst `llm-node`; nichts ist auf diesen Host oder auf lokale Python-Umgebungen zugeschnitten.
|
||||
- Ollama und GLiNER sind gemeinsame Dienste pro Host. Dev und Prod haben getrennte Konfiguration, Volumes und Compose-Projekte.
|
||||
- Die produktive Qdrant-Instanz bleibt unverändert; Dev hat eine eigene Instanz.
|
||||
- Embeddings: `nomic-embed-text`, 768 Dimensionen. Ein Rückfall auf MiniLM/384 wird technisch verhindert.
|
||||
- Vault vom NAS, nur lesend. Dev bekommt Testdaten. Prod-Schreibzugriff bleibt gesperrt, bis R2 behoben ist.
|
||||
- Containerisierung und Privacy Gateway sind getrennt. Keine echten Vault-Inhalte an Cloud-Anbieter.
|
||||
|
||||
## 2. Befunde aus Phase 0
|
||||
|
||||
| Befund | Auswirkung |
|
||||
| --- | --- |
|
||||
| **Gitea-Repo `Lars/mindnet` ist öffentlich** (`private: false`, anonymes `git ls-remote` möglich) | Push der Gateway-Arbeit **nicht** durchgeführt. Sicherung nur lokal (Commits + Bundle). |
|
||||
| Push auf `main` löst `.gitea/workflows/deploy.yml` aus: `rsync --delete` von `app scripts schemas docker tests config …` nach `/home/llmadmin/mindnet` plus Neustart | Jeder Merge nach `main` ist ein Produktions-Deploy. Container-Dateien liegen deshalb in `deploy/` (nicht synchronisiert). |
|
||||
| `config/prod.env` ist versioniert; Key-Felder enthalten in allen Ständen nur Platzhalter (Länge 9/12) | Kein Leak. Datei bleibt ungenutzt; das Image schließt `config/*.env` aus. |
|
||||
| MiniLM: `app/embeddings.py` und `embed_router` sind nicht eingebunden. `docker/embeddings.Dockerfile` kopiert das nicht mehr existierende `app/embed_server.py`. `mindnet-embed` läuft laut Handbuch auf llm-node | Nicht entfernt. Abschaltung erst nach Prüfung auf llm-node (Gate G2). |
|
||||
| `qdrant.py` fällt ohne `VECTOR_DIM` auf 384 zurück; `IngestionProcessor` legt Collections beim Start an | Preflight erzwingt `VECTOR_DIM=768`. |
|
||||
| Ohne Cloud-Keys ruft der stabile Code Ollama mit Cloud-Modell-IDs auf (R4) | Chat lokal nur über Fallback-Kette; langsamer, aber ohne Egress. |
|
||||
|
||||
## 3. Branches
|
||||
|
||||
| Branch | Basis | Inhalt | Ort |
|
||||
| --- | --- | --- | --- |
|
||||
| `main` | — | Produktion (systemd, Auto-Deploy) | Gitea |
|
||||
| `develop` | `origin/main` (`0d61a9e`) | Integrationszweig nach Kansho-Muster; Push deployt Dev (G3) | Gitea |
|
||||
| `feature/containerization` | `develop` | Phase 1 | **nur lokal** |
|
||||
| `codex/privacy-gateway` | `origin/main` | Gateway (2 Commits), unverändert | **nur lokal** + Bundle |
|
||||
| `origin/SectionType` | `origin/main` | WP-26; R3 offen | Gitea |
|
||||
|
||||
Reihenfolge: `feature/containerization` → `develop`. Das Gateway folgt erst nach der Docker-Anpassung aus Abschnitt 6 und als eigener Merge. Ein Konflikt mit dem Gateway-Branch ist nicht zu erwarten: `deploy/`, `.dockerignore` und die neuen Docs/Tests sind neu, `.gitignore` nur auf dem Gateway-Branch.
|
||||
|
||||
## 4. Testbaseline (17 bestehende Fehler, kategorisiert)
|
||||
|
||||
Gleiches Ergebnis mit lokaler venv und mit einer frischen venv aus `deploy/requirements.lock`: 12 failed, 5 errors. Keiner davon wurde deaktiviert.
|
||||
|
||||
| Kategorie | Tests | Ursache | Empfehlung |
|
||||
| --- | --- | --- | --- |
|
||||
| **A – echter Produktfehler** | `test_query_text_embed_unit::test_query_with_text` | `app/routers/query.py:28` übergibt `log_search(req, res)`; Signatur ist `(query_id, query_text, results, …)`. Das Suchprotokoll für `/query` schlägt im Hintergrund fehl. | Aufruf korrigieren (eigener Fix). |
|
||||
| **A – echter Produktfehler** | `test_query_unit::test_query_hybrid_with_monkeypatch`, `test_retriever_basic::test_hybrid_retrieve_basic` | `retriever.py:401` loggt `req.query[:100]`; bei reiner Vektor-Abfrage ist `query=None` → `TypeError` → HTTP 500. | Logging `None`-sicher machen (eigener Fix). |
|
||||
| **B – veralteter Test (API umgebaut)** | `test_final_wp15_validation`, `test_smart_chunking_integration`, `test_wp15_final` (Collection-Error) | `from app.core import chunker` – Modul existiert nicht mehr (jetzt `app/core/chunking/`). | Auf neue API portieren oder bewusst archivieren. |
|
||||
| B | `test_WP22_intelligence` (4) | `EdgeRegistry(vault_root=…)` – Parameter entfernt. | Portieren. |
|
||||
| B | `test_dialog_full_flow` (2) | `save_note()` verlangt `background_tasks`. | Portieren. |
|
||||
| **C – fachlich klären** | `test_type_registry::test_defaults_when_missing` | Test erwartet `chunk_profile`, Code liefert `chunking_profile`. | Entscheiden, welcher Schlüssel gilt. |
|
||||
| C | `test_retriever_edges::test_hybrid_retrieve_uses_edge_scores` | Erwartetes Ranking (`note:2` vor `note:1`) tritt nicht ein. | Prüfen, ob Edge-Scoring regressiert oder Erwartung veraltet ist. |
|
||||
| **D – braucht Infrastruktur / falsch gepatcht** | `test_graph_unit::test_graph_neighbors` | Patcht nicht mehr die tatsächlich aufgerufene Funktion → echte Qdrant-Verbindung. | Patch korrigieren; danach Unit-Test ohne Qdrant. |
|
||||
| **E – kein pytest-Test** | `test_interview_intent::test_intent`, `test_wp06_decision::test_decision_engine` | Funktionsparameter `message`/`query` werden als Fixture interpretiert; manuelle Skripte gegen laufende Dienste. | Nach `scripts/` verschieben oder als Integrationstest mit Marker. |
|
||||
|
||||
Für eine CI-Pipeline wie bei Kansho: zuerst A beheben, B/D portieren, C entscheiden, E umziehen. Danach ist die Baseline ehrlich grün. Bis dahin läuft die volle Suite in `deploy/deploy.sh` nur informativ; blockierend sind die Container-Tests. Nächster Schritt dafür: eine explizite Liste dieser 17 Fälle, gegen die neue Fehler den Deploy stoppen.
|
||||
|
||||
## 5. Freigabe-Gates
|
||||
|
||||
| Gate | Inhalt | Wer |
|
||||
| --- | --- | --- |
|
||||
| **G0** | Repo `Lars/mindnet` auf privat stellen (oder anderes privates Ziel benennen); danach Push von `codex/privacy-gateway`, `develop`, `feature/containerization` | Lars |
|
||||
| **G1** | Review dieses Stands; Merge `feature/containerization` → `develop` | Lars |
|
||||
| **G2** | **Nur lesende** Prüfungen auf llm-node: Docker-/Compose-Version, Port-Bindung Qdrant/Ollama (`ss -ltnp`), `docker ps` (läuft `mindnet-embed`?), `pip freeze` der Prod-venv, NAS-Mount (`findmnt`), Lesbarkeit für UID 10001 | Freigabe Lars |
|
||||
| **G3** | Dev-Container auf llm-node mit derselben Konfiguration wie systemd-Dev (`.env`, Vault, Qdrant-Präfix), parallel auf 8012/8512, `preflight --live`; `.gitea/workflows/deploy-dev.yml` aktiv, jeder Push auf `develop` deployt Dev | **freigegeben 28.10.2026** |
|
||||
| **G4** | Prod-Container parallel zu systemd starten (nur lesend auf Prod-Qdrant, Vault `ro`), Vergleich der Antworten | Freigabe Lars |
|
||||
| **G5** | Umschaltung Prod auf Container; systemd 2–3 Wochen als Rückfallebene; im selben Commit `deploy-prod.yml` aktivieren und `.gitea/workflows/deploy.yml` entfernen | Freigabe Lars; Voraussetzung R2, falls Schreibzugriff nötig |
|
||||
|
||||
### R2 – Pfadsicherheit beim Speichern (Pflicht vor beschreibbarem Vault)
|
||||
|
||||
`create_from_text` setzt `folder`/`filename` per `os.path.join` zusammen und schreibt ungeprüft. Die Container verhindern das derzeit nur über den schreibgeschützten Mount. Vor jedem beschreibbaren Prod-Vault: aufgelösten Zielpfad gegen den aufgelösten Vault prüfen, absolute Pfade und `..` ablehnen, Symlinks berücksichtigen, Überschreibregeln festlegen, Tests ergänzen. Zusätzlich gehört vor `/ingest/*` eine Zugriffsgrenze (Authentisierung).
|
||||
|
||||
### R3 – Section-Types (Pflichtkorrektur vor Integration von `SectionType`)
|
||||
|
||||
`_propagate_section_type_backwards` gruppiert fest auf H2 und überträgt den ersten Typ auf alle Blöcke. Zwei H3-Abschnitte mit unterschiedlichen Typen erhalten denselben Typ, und der H2-Elterntext wird umtypisiert (Reproduktion im Review). **Gesonderte Korrektur** auf dem `SectionType`-Branch mit verschachteltem Regressionstest. Erst danach Merge nach `develop`. In diesem Arbeitspaket bewusst nicht behoben.
|
||||
|
||||
## 6. Phase 2: Privacy Gateway im Container (Anforderungen)
|
||||
|
||||
Gilt für die spätere Anpassung von `require_local_endpoint` und `LocalDetector`. Grundsatz bleibt fail-closed.
|
||||
|
||||
**Zielverbindungen.** Eine Host-Allowlist mit einmaliger DNS-Auflösung reicht nicht. Zwischen Prüfung und Verbindung kann der Name auf eine andere Adresse zeigen (DNS-Rebinding), und Redirects oder Proxies können das Ziel wechseln. Anforderungen:
|
||||
|
||||
1. Allowlist erlaubter Dienste mit Name, Port und Schema (`ollama:11434`, `gliner:8090`), keine Wildcards.
|
||||
2. Auflösung **pro Verbindung**; alle aufgelösten Adressen müssen in erlaubten Netzen liegen (bevorzugt im Compose-Subnetz statt pauschal RFC1918). Sonst Abbruch.
|
||||
3. **Verbinden auf die geprüfte IP** (Pinning über eigenen httpx-Transport bzw. Resolver), Host-Header bzw. SNI bleibt der Name. Danach die tatsächliche Gegenstelle des Sockets (`getpeername`) gegen die geprüfte IP vergleichen.
|
||||
4. `follow_redirects=False`, `trust_env=False` (keine Proxies), keine URL-Credentials; Antwort-Redirects sind Fehler.
|
||||
5. Netzwerkseitig zusätzlich absichern: Detector und Ollama in einem `internal: true`-Netz ohne Internetzugang. Ausgehender Cloud-Verkehr nur aus dem API-Container und perspektivisch über einen Egress-Proxy mit Provider-Allowlist.
|
||||
6. Tests: Rebinding-Simulation (zweite Auflösung liefert öffentliche IP), Redirect-Antwort, Proxy-Variablen gesetzt, IPv6-mapped-IPv4, Link-Local/Metadaten-IP (`169.254.169.254`).
|
||||
|
||||
**Ausfall der Personenerkennung.** Cloud-Aufrufe werden blockiert (`PrivacyError`, kein Fallback). Das ist im Gateway-Branch bereits so umgesetzt.
|
||||
|
||||
**Wiederholungsmechanismus für die Ingestion (Entwurf).** Bisher bekommt eine Notiz `status: error`, wenn die Kantenvalidierung an einem `PrivacyError` scheitert. Ziel ist eine nachvollziehbare, nicht stille Wiederholung:
|
||||
|
||||
1. **Kein Teil-Commit:** Note, Chunks und explizite Kanten werden geschrieben. Kandidaten-Kanten, deren Validierung nicht möglich war, werden **nicht** verworfen und **nicht** als validiert markiert. Sie bleiben mit `validation_state: pending` und einem Reason-Code (`local_detection_failed`, `local_endpoint_required`, …) erhalten.
|
||||
2. **Persistente Warteschlange** im `data`-Volume (z. B. SQLite `data/ingest_retry.db`), Schlüssel `(note_id, content_hash)`: Versuchszähler, `next_attempt_at` mit exponentiellem Backoff, letzter Reason-Code. Keine Inhalte, nur Referenzen.
|
||||
3. **Idempotenz:** Ändert sich die Notiz, wird der alte Eintrag durch den neuen Hash ersetzt. Wiederholung verarbeitet nur die offenen Kandidaten.
|
||||
4. **Auslösung:** Zunächst **manuell** (CLI-Skript bzw. Admin-Endpoint). Ein automatischer Scheduler erst nach gesonderter Freigabe, weil er gegen Produktivdaten läuft.
|
||||
5. **Sichtbarkeit:** `/admin/stats` und Healthcheck-Details melden Anzahl `pending`/`failed`; nach `max_attempts` Status `failed` mit Reason-Code, nie stilles Verwerfen.
|
||||
6. **Tests:** Detector-Ausfall während der Ingestion → Note vorhanden, Kandidaten `pending`, Queue-Eintrag. Erneuter Lauf mit verfügbarem Detector → validiert, Eintrag entfernt.
|
||||
|
||||
## 7. Nächste Schritte
|
||||
|
||||
1. G0: Repo-Sichtbarkeit klären.
|
||||
2. G1: Review/Merge von `feature/containerization` nach `develop`.
|
||||
3. G2: lesende Prüfungen auf llm-node (Kommandos in [Container-Betrieb §4–5](../04_Operations/04_docker_deployment.md)).
|
||||
4. Fix-Pakete A (query/retriever) und R3 separat; Gateway-Anpassung nach Abschnitt 6.
|
||||
@@ -0,0 +1,250 @@
|
||||
<!-- DOCUMENT 1: pflichtenheft_obsidian_plugin_mindnet_assistant.md -->
|
||||
---
|
||||
id: pflichtenheft_obsidian_plugin_mindnet_assistant
|
||||
title: Pflichtenheft – Obsidian Plugin „Mindnet Causal Assistant“
|
||||
type: specification
|
||||
status: draft
|
||||
created: 2026-01-13
|
||||
lang: de
|
||||
---
|
||||
|
||||
# Pflichtenheft – Obsidian Plugin „Mindnet Causal Assistant“
|
||||
|
||||
## 1. Zielsetzung
|
||||
Das Plugin unterstützt den Nutzer beim Erstellen und Pflegen eines narrativ-kausalen Wissensgraphen in Obsidian (Mindnet).
|
||||
|
||||
Es bietet:
|
||||
- **Aktive Authoring-Unterstützung** (Guided Note Creation / Interview Flow)
|
||||
- **Kausalketten-Prüfung** (Chain Explorer, Vorwärts/Rückwärts)
|
||||
- **Linting + Auto-Fixes** (Graph-Hygiene, konsistente Kanten, Namensnormalisierung)
|
||||
- **Export/Integration** der strukturierten Graph-Daten für ein Retrieval-System (Qdrant + Graph-Index)
|
||||
|
||||
## 2. Kontext & Randbedingungen
|
||||
- Obsidian Vault enthält Notes als Markdown, jede Entität eine Datei.
|
||||
- Notes enthalten Frontmatter (`id,title,type,status,...`) und Edges in Callout-Blöcken.
|
||||
- Edge-Vokabular inklusive Aliasse & Inversen ist verfügbar (z.B. `edge_vocabulary.md`).
|
||||
- Der Graph soll später von Mindnet traversierbar sein (Vorwärts/Rückwärts über inverse Relationen).
|
||||
- Plugin muss offline nutzbar sein; optionale Backend/LLM-Integration ist konfigurierbar.
|
||||
|
||||
## 3. Begriffsdefinitionen
|
||||
- **Node**: eine Obsidian Markdown-Datei (Entität).
|
||||
- **Edge**: gerichtete Beziehung zwischen zwei Nodes (canonical edge type).
|
||||
- **Alias**: alternative Edge-Bezeichnung in Notes, die auf canonical mapped wird.
|
||||
- **Inverse**: Gegenkante zu einer Edge, laut Vokabular (z.B. `resulted_in` ⇄ `caused_by`).
|
||||
- **Hub/Index**: Note, die primär navigiert (typisch `type: insight`), keine Kausalursache.
|
||||
|
||||
## 4. Scope
|
||||
### In Scope (MVP → V2)
|
||||
**MVP**
|
||||
- Parser für Frontmatter + Edge-Callouts
|
||||
- Normalizer: Alias → Canonical; optional Inversen-Erkennung
|
||||
- Linter: Regelset (Error/Warn/Info) + Report
|
||||
- Chain Explorer: forward/backward traversal (1–4 hops) ab aktueller Note
|
||||
- Quickfixes: Edge-Typ ersetzen, Links normalisieren, Missing Note Stub erzeugen
|
||||
|
||||
**V2**
|
||||
- Guided Authoring (Interview Flow) für `experience/decision/principle/state/strategy`
|
||||
- Refactor Mode: Text → Node/Edge-Kandidaten + Review UI
|
||||
- Export/Sync: JSON Graph Export + optional Qdrant Sync (separater Service)
|
||||
|
||||
### Out of Scope (initial)
|
||||
- Vollautomatische Kausalitäts-Interpretation ohne User-Bestätigung
|
||||
- Vollständige UI-Graph-Visualisierung (Obsidian Graph View bleibt nutzbar)
|
||||
- Direkte medizinische/psychologische Beratung
|
||||
|
||||
## 5. Nutzerrollen & Use Cases
|
||||
### Rolle: Nutzer (Author)
|
||||
- UC1: „Ich schreibe eine Note und will Kanten prüfen“
|
||||
- UC2: „Ich will von einem Ereignis aus die Kausalkette sehen“
|
||||
- UC3: „Ich will eine neue Experience/Decision Note sauber anlegen“
|
||||
- UC4: „Ich habe Text und will daraus Kandidaten extrahieren“
|
||||
- UC5: „Ich will leere Links als open_question sauber erzeugen“
|
||||
|
||||
### Rolle: System/Indexer (Mindnet)
|
||||
- UC6: „Ich brauche exportierbare adjacency lists + canonical edges“
|
||||
|
||||
## 6. Funktionale Anforderungen (FR)
|
||||
|
||||
### FR1: Vault Parsing
|
||||
- FR1.1 Parse Frontmatter (YAML): `id,title,type,status,date,tags,...`
|
||||
- FR1.2 Parse Edge-Callouts im Format:
|
||||
- `> [!abstract]- 🕸️ Semantic Mapping`
|
||||
- `>> [!edge] <relation>`
|
||||
- `>> [[target]]`
|
||||
- FR1.3 Extrahiere alle WikiLinks `[[...]]` aus Edge-Blocks
|
||||
- FR1.4 Erkenne Datei-Pfade, Dateinamen und canonical node identifiers (Dateiname ohne `.md`)
|
||||
|
||||
**Output (intern)**
|
||||
```ts
|
||||
type Node = { id?: string; title?: string; type?: string; status?: string; path: string; slug: string };
|
||||
type Edge = { srcSlug: string; dstSlug: string; rawType: string; canonicalType?: string; line?: number; blockId?: string };
|
||||
```
|
||||
|
||||
### FR2: Edge Normalization
|
||||
- FR2.1 Map rawType/Alias auf canonical edge type via Edge Vocabulary
|
||||
- FR2.2 Speichere Mapping-Entscheidungen (raw → canonical) pro Edge
|
||||
- FR2.3 Liefere inverse edge type (`inverseType`) pro canonical edge type (sofern definiert)
|
||||
|
||||
### FR3: Linting
|
||||
- FR3.1 Führe Checkliste von Regeln aus (siehe separates Dokument)
|
||||
- FR3.2 Liefere LintReport mit Severity (ERROR/WARN/INFO), Location (file, line), Fix-Vorschlägen
|
||||
- FR3.3 Quickfix: wende Fix auf Note an (Text edit), mit Preview/Diff
|
||||
|
||||
### FR4: Chain Explorer (Traversal)
|
||||
- FR4.1 Startpunkt: aktuelle Note im Editor
|
||||
- FR4.2 Forward traversal: `resulted_in`, `followed_by`, `impacts`, `source_of`, optional `related_to`
|
||||
- FR4.3 Backward traversal: `caused_by`, `preceeded_by`, `derived_from`, `impacted_by`
|
||||
- FR4.4 Konfigurierbare maxHops (Default 3)
|
||||
- FR4.5 Ergebnis als Liste von Pfaden + kompaktes Subgraph-Summary (Nodes/Edges)
|
||||
|
||||
### FR5: Missing Notes / Stubs
|
||||
- FR5.1 Erkenne, wenn Edge-Target nicht existiert
|
||||
- FR5.2 Biete „Create Stub Note“ an:
|
||||
- Template basierend auf Typ (default `open_question` wenn unbekannt)
|
||||
- Einhaltung Naming-Rules: `a-z0-9_`
|
||||
- FR5.3 Optional: convert TODO-Link → open_question note
|
||||
|
||||
### FR6: Guided Authoring (V2)
|
||||
- FR6.1 Wizard für neue Notes: Auswahl Typ → Fragen (eine nach der anderen)
|
||||
- FR6.2 Wizard erstellt Datei mit Template + initialen Edge-Blocks
|
||||
- FR6.3 Jede automatische Edge-Vermutung ist „review-required“
|
||||
|
||||
### FR7: Refactor Mode (V2)
|
||||
- FR7.1 Extrahiere aus aktuellem Note-Text Kandidaten:
|
||||
- Event-Kandidaten (Datum/Ort/Verben)
|
||||
- Decision-Kandidaten („entschied“, „nahm an“, „wechselte“)
|
||||
- Principle-Kandidaten („ich glaube“, „ich habe gelernt“)
|
||||
- Relation-Kandidaten („dadurch“, „führte zu“, „weil“)
|
||||
- FR7.2 UI-Review: Checkbox-Liste zum Erstellen/Verwerfen
|
||||
- FR7.3 Generiere Notes + Edges nur nach Bestätigung
|
||||
|
||||
### FR8: Export (MVP optional / V2 empfohlen)
|
||||
- FR8.1 Export JSON: Nodes + canonical edges + inverses
|
||||
- FR8.2 Export adjacency list pro node slug
|
||||
- FR8.3 Optional: webhook/CLI hook für Indexer (Qdrant)
|
||||
|
||||
## 7. Nicht-funktionale Anforderungen (NFR)
|
||||
- NFR1: Performant bei 10k Notes (incremental parse, caching)
|
||||
- NFR2: Offline-first; LLM/Backend optional
|
||||
- NFR3: Deterministische Normalisierung (gleiches Input → gleiches Output)
|
||||
- NFR4: Kein Erfinden von Fakten: Auto-Edge nur als Vorschlag
|
||||
- NFR5: Sicheres Editieren (Diff/Undo via Obsidian APIs)
|
||||
- NFR6: Konfigurierbarkeit (YAML/Settings Tab): maxHops, allowed edges, strict mode
|
||||
|
||||
## 8. Technisches Lösungsdesign
|
||||
|
||||
### 8.1 Obsidian Plugin Struktur (TypeScript)
|
||||
- `main.ts` – Plugin lifecycle, commands, views
|
||||
- `settings.ts` – Einstellungen
|
||||
- `parser/` – Markdown + callout parser
|
||||
- `graph/` – Node/Edge model, normalization, traversal
|
||||
- `lint/` – Rules engine, reports, quickfixes
|
||||
- `ui/` – Sidebar view, modals, diff preview
|
||||
|
||||
### 8.2 Speicherung / Cache
|
||||
- In-memory cache: map `path → parsed Node + edges + hash`
|
||||
- Incremental update: on file change events re-parse only changed file
|
||||
- Optional persisted cache in `.obsidian/plugins/.../cache.json`
|
||||
|
||||
### 8.3 Edge Vocabulary Integration
|
||||
- Input: `edge_vocabulary.md` im Vault ODER eingebettete JSON Ressource
|
||||
- Parsing:
|
||||
- canonical edge types
|
||||
- alias list
|
||||
- inverse mapping
|
||||
- Fallback: minimal builtin vocabulary, wenn Datei fehlt
|
||||
|
||||
### 8.4 Traversal Engine
|
||||
- Graph Index: adjacency lists aus canonical edges
|
||||
- Traversal:
|
||||
- BFS mit hop limit
|
||||
- optional weighted expansion (für Chain Explorer „relevant paths first“)
|
||||
|
||||
### 8.5 Quickfix Engine
|
||||
- Applies patches auf Markdown:
|
||||
- Replace edge type token im Callout (`>> [!edge] ...`)
|
||||
- Rename link targets (replace `[[old]]` → `[[new]]`)
|
||||
- Insert stub note file from template
|
||||
- Safety:
|
||||
- Show diff modal
|
||||
- Use Obsidian editor transactions / file API
|
||||
|
||||
### 8.6 Optional Backend / LLM (V2)
|
||||
- Backend (local node service) für:
|
||||
- text extraction (Refactor Mode)
|
||||
- suggestion generation
|
||||
- Communication:
|
||||
- HTTP local (`127.0.0.1`) oder WebSocket
|
||||
- API key storage via Obsidian settings (encrypted if possible)
|
||||
- Claude-code/Cursor: nutzt Code-Agent für Implementierung, nicht zur Runtime.
|
||||
|
||||
## 9. UI/UX Anforderungen
|
||||
|
||||
### 9.1 Sidebar View „Mindnet Assistant“
|
||||
Tabs:
|
||||
- **Validate**: Lint Report + Fix Buttons
|
||||
- **Chains**: Forward/Backward Chain Explorer + Copy as text
|
||||
- **Create** (V2): Wizard new note
|
||||
- **Refactor** (V2): Extract candidates
|
||||
|
||||
### 9.2 Commands (Command Palette)
|
||||
- `Mindnet: Validate current note`
|
||||
- `Mindnet: Validate vault (selected folders)`
|
||||
- `Mindnet: Show chains from current note`
|
||||
- `Mindnet: Normalize edges in current note`
|
||||
- `Mindnet: Create stub for missing links`
|
||||
- (V2) `Mindnet: Start guided authoring`
|
||||
- (V2) `Mindnet: Refactor current note to graph`
|
||||
|
||||
## 10. Akzeptanzkriterien
|
||||
- AK1: Plugin erkennt Edge-Callouts und normalisiert Aliasse deterministisch
|
||||
- AK2: Linter findet Node-Splitting (mindestens Levenshtein/ähnliche Slugs) und Missing Notes
|
||||
- AK3: Chain Explorer liefert identische Pfade vorwärts/rückwärts bei inversen Edge-Paaren
|
||||
- AK4: Quickfix ersetzt Edge-Typen ohne Markdown zu zerstören; Undo funktioniert
|
||||
- AK5: Export JSON enthält canonical edges + inverse types
|
||||
|
||||
## 11. Deliverables
|
||||
- Obsidian Plugin (TS) mit MVP Features
|
||||
- Dokumentation:
|
||||
- Install/Build
|
||||
- Settings
|
||||
- Rule reference
|
||||
- Example vault sample
|
||||
- Optional: JSON Export Format Spec (nodes/edges)
|
||||
|
||||
---
|
||||
|
||||
## 12. Prompts für Code-Agenten (Cursor / Claude-code)
|
||||
|
||||
### Prompt A (Repo Scaffold + MVP)
|
||||
> Du bist ein Senior TypeScript Engineer. Implementiere ein Obsidian Plugin „Mindnet Causal Assistant“.
|
||||
> Ziele MVP:
|
||||
> 1) Parse Frontmatter (YAML) und Edge-Callouts im Format:
|
||||
> `> [!abstract]- 🕸️ Semantic Mapping` → `>> [!edge] <relation>` → `>> [[target]]`.
|
||||
> 2) Normalisiere Edge Aliasse auf canonical edge types (Vokabular als JSON im Code; später ersetzbar).
|
||||
> 3) Baue eine Sidebar View mit Tabs „Validate“ und „Chains“.
|
||||
> 4) Implementiere Lint Regeln: missing target note, alias-not-normalized, hub-has-causal-edge, chronology-vs-causality warning.
|
||||
> 5) Implementiere Chain Explorer (forward/backward, maxHops=3).
|
||||
> 6) Implementiere Quickfix: replace edge type token, create stub note.
|
||||
> Nutze Obsidian APIs, schreibe sauberen TS Code, mit Tests für Parser/Normalizer.
|
||||
|
||||
### Prompt B (Parser Unit Tests)
|
||||
> Schreibe Unit Tests für den Markdown Parser:
|
||||
> - erkennt mehrere Edge-Blocks pro Datei
|
||||
> - erkennt mehrere Targets pro Edge
|
||||
> - liefert line numbers
|
||||
> - ignoriert WikiLinks außerhalb der Semantic Mapping Callouts
|
||||
> Nutze vitest/jest. Erzeuge fixtures.
|
||||
|
||||
### Prompt C (Lint Engine + Quickfix)
|
||||
> Implementiere eine Lint Engine als Rule-Pipeline.
|
||||
> Jede Regel: id, severity, detect(node, graph) -> findings, fix(finding)->patch.
|
||||
> Baue eine Diff Preview Modal und applyPatch über Obsidian file API.
|
||||
> Implementiere zunächst 6 Regeln aus der Checkliste.
|
||||
|
||||
### Prompt D (Vocabulary Loader)
|
||||
> Implementiere einen VocabularyLoader:
|
||||
> - lädt entweder eingebettetes JSON oder eine Vault-Datei `edge_vocabulary.md`
|
||||
> - parst canonical types, aliases, inverse
|
||||
> - bietet getCanonical(raw) und getInverse(canonical)
|
||||
> Fallback auf builtin vocabulary wenn parsing fehlschlägt.
|
||||
@@ -0,0 +1,136 @@
|
||||
<!-- DOCUMENT 2: checklist_lint_regeln_mindnet_assistant.md -->
|
||||
---
|
||||
id: checklist_lint_regeln_mindnet_assistant
|
||||
title: Checkliste – Lint-Regeln für Mindnet Causal Assistant
|
||||
type: specification
|
||||
status: draft
|
||||
created: 2026-01-13
|
||||
lang: de
|
||||
---
|
||||
|
||||
# Checkliste – Lint-Regeln für Mindnet Causal Assistant
|
||||
|
||||
## Severity Levels
|
||||
- **ERROR**: bricht Traversal/Indexer oder erzeugt falsche Nodes
|
||||
- **WARN**: wahrscheinlich falsche Semantik / schlechter Retrieval-Impact
|
||||
- **INFO**: Optimierung / Empfehlung
|
||||
|
||||
---
|
||||
|
||||
## A. Graph-Integrität & Naming
|
||||
|
||||
### L1 (ERROR) Missing Target Note
|
||||
**Wenn:** Edge target `[[X]]` existiert nicht als Datei im Vault
|
||||
**Dann:** Finding `missing_target`
|
||||
**Fix:** „Create Stub Note“ (default `type: open_question`) oder remove edge
|
||||
|
||||
### L2 (ERROR) Node Splitting durch Schreibvarianten
|
||||
**Wenn:** mehrere Targets im Vault sind ähnlich (slug distance), oder in Edges mehrere Varianten vorkommen
|
||||
**Dann:** Finding `node_split_candidate`
|
||||
**Fix:** Vorschlag canonical slug + bulk replace links
|
||||
|
||||
### L3 (ERROR) Invalid Filename Policy
|
||||
**Wenn:** Dateiname enthält Zeichen außerhalb `[a-z0-9_]`
|
||||
**Dann:** Finding `invalid_filename`
|
||||
**Fix:** Rename file + update all backlinks
|
||||
|
||||
---
|
||||
|
||||
## B. Edge-Formale Regeln
|
||||
|
||||
### L4 (ERROR) Unknown Edge Type / Unmapped Alias
|
||||
**Wenn:** raw edge type nicht im Vokabular (alias→canonical)
|
||||
**Dann:** Finding `unknown_edge_type`
|
||||
**Fix:** Edge type ersetzen durch best guess oder user selection
|
||||
|
||||
### L5 (WARN) Alias not normalized
|
||||
**Wenn:** raw edge type ist Alias, canonical bekannt, aber Note enthält Alias
|
||||
**Dann:** Finding `alias_not_normalized`
|
||||
**Fix:** Replace raw with canonical (optional config)
|
||||
|
||||
### L6 (WARN) Missing Inverse Edge (optional strict mode)
|
||||
**Wenn:** Edge A->B existiert, inverse nach Vokabular fehlt in B
|
||||
**Dann:** Finding `missing_inverse`
|
||||
**Fix:** Add inverse edge to target note (review + diff)
|
||||
|
||||
---
|
||||
|
||||
## C. Semantik: Kausalität vs Chronologie
|
||||
|
||||
### L7 (WARN) Chronology used as Causality
|
||||
**Wenn:** Knoten/Target wirkt wie Prozessschritt („warten“, „gehen“, „ankommen“) und Edge type ist `resulted_in`
|
||||
**Dann:** Finding `chronology_as_causality`
|
||||
**Fix:** Vorschlag `followed_by` (inverse `preceeded_by`)
|
||||
|
||||
### L8 (INFO) Kausalität ohne Brücken (Gap)
|
||||
**Wenn:** Pfad springt von Ereignis direkt zu Entscheidung, aber intermediäre Knoten fehlen (heuristisch)
|
||||
**Dann:** Finding `missing_bridge_node`
|
||||
**Fix:** Vorschlag „Create open_question bridge“ (z.B. „Was war der konkrete Auslöser…?“)
|
||||
|
||||
---
|
||||
|
||||
## D. Node-Type Regeln
|
||||
|
||||
### L9 (ERROR) Causal edges from open_question/hypothesis/white_spot
|
||||
**Wenn:** node.type in `{open_question, hypothesis, white_spot}` und Edge type in `{caused_by, resulted_in, impacts, derived_from}`
|
||||
**Dann:** Finding `invalid_causal_edge_from_uncertain`
|
||||
**Fix:** Replace with `related_to` oder remove edge
|
||||
|
||||
### L10 (WARN) Hub/Insight Note trägt Kausalität
|
||||
**Wenn:** node.type == `insight` (oder Hub-Pattern) und hat `caused_by/resulted_in`
|
||||
**Dann:** Finding `hub_has_causality`
|
||||
**Fix:** Replace edges with `related_to` und verschiebe Kausalität in atomare Notes
|
||||
|
||||
### L11 (WARN) Principle uses caused_by for origin
|
||||
**Wenn:** node.type == `principle` und enthält `caused_by` zu Erlebnissen
|
||||
**Dann:** Finding `principle_origin_edge`
|
||||
**Fix:** Vorschlag `derived_from` oder `based_on`
|
||||
|
||||
### L12 (INFO) Decision without caused_by
|
||||
**Wenn:** node.type == `decision` und hat keine `caused_by`-Kanten
|
||||
**Dann:** Finding `decision_without_causes`
|
||||
**Fix:** Wizard: „Was war der Auslöser?“ → create open_question or add edges
|
||||
|
||||
---
|
||||
|
||||
## E. Redundanz & Zyklen
|
||||
|
||||
### L13 (WARN) Duplicate Edges
|
||||
**Wenn:** identische canonical edge mehrfach gesetzt (src,type,dst)
|
||||
**Dann:** Finding `duplicate_edge`
|
||||
**Fix:** remove duplicates
|
||||
|
||||
### L14 (WARN) Cycles in pure causality subgraph
|
||||
**Wenn:** Zyklus ausschließlich über `{caused_by,resulted_in,derived_from,source_of}`
|
||||
**Dann:** Finding `causal_cycle`
|
||||
**Fix:** Markiere zur Review; oft ist eine Kante falsch gerichtet
|
||||
|
||||
---
|
||||
|
||||
## F. Traversal-Optimierung (Retrieval-Wirkung)
|
||||
|
||||
### L15 (INFO) Overuse of related_to
|
||||
**Wenn:** Note enthält nur `related_to` und keine spezifischeren Kanten
|
||||
**Dann:** Finding `weak_semantics`
|
||||
**Fix:** Vorschlag: präzisere Beziehungstypen setzen
|
||||
|
||||
### L16 (INFO) Missing type metadata
|
||||
**Wenn:** Frontmatter `type` fehlt
|
||||
**Dann:** Finding `missing_type`
|
||||
**Fix:** Prompt user to choose type; set via template
|
||||
|
||||
### L17 (INFO) Missing date on experience
|
||||
**Wenn:** node.type == `experience` und kein Datum/Zeitraum vorhanden
|
||||
**Dann:** Finding `missing_date_experience`
|
||||
**Fix:** Prompt: „Wann ungefähr?“ → set `date` oder `time_range`
|
||||
|
||||
---
|
||||
|
||||
## Suggested Implementation Notes
|
||||
- Jede Regel liefert:
|
||||
- `ruleId`, `severity`, `message`, `location`, `evidence`, `quickFixes[]`
|
||||
- QuickFixes sind Patch-Operationen:
|
||||
- replaceText(range, text)
|
||||
- insertBlock(atLine, block)
|
||||
- createFile(path, content)
|
||||
- renameFile(old, new) + updateLinks(glob)
|
||||
Generated
+6
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"name": "mindnet",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {}
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Script zur Verifikation der EdgeDTO-Import-Version in Prod.
|
||||
Prüft, ob die korrekte Version des EdgeDTO-Modells geladen wird.
|
||||
"""
|
||||
import sys
|
||||
import os
|
||||
|
||||
# Stelle sicher, dass der Projekt-Pfad im Python-Path ist
|
||||
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
|
||||
try:
|
||||
from app.models.dto import EdgeDTO
|
||||
import inspect
|
||||
|
||||
# Extrahiere die Literal-Definition aus dem Source-Code
|
||||
source = inspect.getsource(EdgeDTO)
|
||||
|
||||
# Prüfe, ob explicit:callout in der Literal-Liste ist
|
||||
if "explicit:callout" in source:
|
||||
print("✅ EdgeDTO unterstützt 'explicit:callout'")
|
||||
print(f" -> Modul-Pfad: {EdgeDTO.__module__}")
|
||||
print(f" -> Datei: {inspect.getfile(EdgeDTO)}")
|
||||
|
||||
# Zeige die Provenance-Definition
|
||||
import re
|
||||
match = re.search(r'provenance.*?Literal\[(.*?)\]', source, re.DOTALL)
|
||||
if match:
|
||||
literal_values = match.group(1)
|
||||
if "explicit:callout" in literal_values:
|
||||
print("✅ 'explicit:callout' ist in der Literal-Liste enthalten")
|
||||
print(f"\n Literal-Werte (erste 200 Zeichen):\n {literal_values[:200]}...")
|
||||
else:
|
||||
print("❌ 'explicit:callout' ist NICHT in der Literal-Liste!")
|
||||
print(f"\n Gefundene Literal-Werte:\n {literal_values}")
|
||||
else:
|
||||
print("⚠️ Konnte Literal-Definition nicht finden")
|
||||
else:
|
||||
print("❌ EdgeDTO unterstützt NICHT 'explicit:callout'")
|
||||
print(f" -> Modul-Pfad: {EdgeDTO.__module__}")
|
||||
print(f" -> Datei: {inspect.getfile(EdgeDTO)}")
|
||||
print("\n Source-Code (erste 500 Zeichen):")
|
||||
print(f" {source[:500]}...")
|
||||
|
||||
# Test: Versuche ein EdgeDTO mit explicit:callout zu erstellen
|
||||
print("\n🧪 Test: Erstelle EdgeDTO mit provenance='explicit:callout'...")
|
||||
try:
|
||||
test_edge = EdgeDTO(
|
||||
id="test",
|
||||
kind="test",
|
||||
source="test",
|
||||
target="test",
|
||||
weight=1.0,
|
||||
provenance="explicit:callout"
|
||||
)
|
||||
print("✅ EdgeDTO mit 'explicit:callout' erfolgreich erstellt!")
|
||||
print(f" -> Provenance: {test_edge.provenance}")
|
||||
except Exception as e:
|
||||
print(f"❌ Fehler beim Erstellen: {e}")
|
||||
print(f" -> Typ: {type(e).__name__}")
|
||||
|
||||
except ImportError as e:
|
||||
print(f"❌ Import-Fehler: {e}")
|
||||
sys.exit(1)
|
||||
except Exception as e:
|
||||
print(f"❌ Unerwarteter Fehler: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
sys.exit(1)
|
||||
@@ -0,0 +1,114 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Script zur Verifikation des .env-Ladens in Prod.
|
||||
Prüft, ob die .env-Datei korrekt geladen wird und welche Werte tatsächlich verwendet werden.
|
||||
"""
|
||||
import os
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
# Stelle sicher, dass der Projekt-Pfad im Python-Path ist
|
||||
project_root = Path(__file__).parent.parent
|
||||
sys.path.insert(0, str(project_root))
|
||||
|
||||
print("=" * 80)
|
||||
print("🔍 .env-Lade-Verifikation")
|
||||
print("=" * 80)
|
||||
|
||||
# 1. Prüfe, ob .env-Datei existiert
|
||||
env_files = [
|
||||
project_root / ".env",
|
||||
project_root / "prod.env",
|
||||
project_root / "config" / "prod.env",
|
||||
Path.cwd() / ".env",
|
||||
Path.cwd() / "prod.env",
|
||||
]
|
||||
|
||||
print("\n1. Suche nach .env-Dateien:")
|
||||
found_env = None
|
||||
for env_file in env_files:
|
||||
if env_file.exists():
|
||||
print(f" ✅ Gefunden: {env_file}")
|
||||
if found_env is None:
|
||||
found_env = env_file
|
||||
else:
|
||||
print(f" ❌ Nicht gefunden: {env_file}")
|
||||
|
||||
if not found_env:
|
||||
print("\n ⚠️ WARNUNG: Keine .env-Datei gefunden!")
|
||||
print(" -> load_dotenv() wird Standard-Werte verwenden")
|
||||
|
||||
# 2. Lade .env manuell
|
||||
print("\n2. Lade .env-Datei:")
|
||||
from dotenv import load_dotenv
|
||||
|
||||
if found_env:
|
||||
result = load_dotenv(found_env, override=True)
|
||||
print(f" ✅ load_dotenv('{found_env}') = {result}")
|
||||
else:
|
||||
result = load_dotenv(override=True)
|
||||
print(f" ⚠️ load_dotenv() ohne expliziten Pfad = {result}")
|
||||
print(" -> Sucht automatisch nach .env im aktuellen Verzeichnis")
|
||||
|
||||
# 3. Prüfe kritische Umgebungsvariablen
|
||||
print("\n3. Kritische Umgebungsvariablen:")
|
||||
critical_vars = [
|
||||
"COLLECTION_PREFIX",
|
||||
"MINDNET_PREFIX",
|
||||
"DEBUG",
|
||||
"VECTOR_DIM",
|
||||
"MINDNET_EMBEDDING_MODEL",
|
||||
"QDRANT_URL",
|
||||
]
|
||||
|
||||
for var in critical_vars:
|
||||
value = os.getenv(var, "NICHT GESETZT")
|
||||
source = "Umgebung" if var in os.environ else "Default/Code"
|
||||
print(f" {var:30} = {value:40} ({source})")
|
||||
|
||||
# 4. Prüfe, welche .env-Datei tatsächlich geladen wurde
|
||||
print("\n4. Verifikation der geladenen Werte:")
|
||||
print(f" Arbeitsverzeichnis: {Path.cwd()}")
|
||||
print(f" Projekt-Root: {project_root}")
|
||||
print(f" Python-Pfad[0]: {sys.path[0] if sys.path else 'N/A'}")
|
||||
|
||||
# 5. Test: Importiere Settings
|
||||
print("\n5. Test: Importiere Settings aus app.config:")
|
||||
try:
|
||||
from app.config import get_settings
|
||||
settings = get_settings()
|
||||
print(f" ✅ Settings erfolgreich geladen")
|
||||
print(f" -> COLLECTION_PREFIX: {settings.COLLECTION_PREFIX}")
|
||||
print(f" -> VECTOR_SIZE: {settings.VECTOR_SIZE}")
|
||||
print(f" -> EMBEDDING_MODEL: {settings.EMBEDDING_MODEL}")
|
||||
except Exception as e:
|
||||
print(f" ❌ Fehler beim Laden der Settings: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
|
||||
# 6. Test: Prüfe EdgeDTO
|
||||
print("\n6. Test: Prüfe EdgeDTO-Import:")
|
||||
try:
|
||||
from app.models.dto import EdgeDTO
|
||||
import inspect
|
||||
|
||||
source = inspect.getsource(EdgeDTO)
|
||||
if "explicit:callout" in source:
|
||||
print(" ✅ EdgeDTO unterstützt 'explicit:callout'")
|
||||
print(f" -> Modul-Pfad: {EdgeDTO.__module__}")
|
||||
print(f" -> Datei: {inspect.getfile(EdgeDTO)}")
|
||||
else:
|
||||
print(" ❌ EdgeDTO unterstützt NICHT 'explicit:callout'")
|
||||
|
||||
# Test-Erstellung
|
||||
test_edge = EdgeDTO(
|
||||
id="test", kind="test", source="test", target="test",
|
||||
weight=1.0, provenance="explicit:callout"
|
||||
)
|
||||
print(" ✅ EdgeDTO mit 'explicit:callout' erfolgreich erstellt!")
|
||||
except Exception as e:
|
||||
print(f" ❌ Fehler: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
|
||||
print("\n" + "=" * 80)
|
||||
@@ -0,0 +1,160 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Script zur Laufzeit-Verifikation des laufenden Mindnet-Services.
|
||||
Prüft, ob der Service die korrekte EdgeDTO-Version verwendet und ob die .env korrekt geladen wurde.
|
||||
"""
|
||||
import sys
|
||||
import requests
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
# Stelle sicher, dass der Projekt-Pfad im Python-Path ist
|
||||
project_root = Path(__file__).parent.parent
|
||||
sys.path.insert(0, str(project_root))
|
||||
|
||||
print("=" * 80)
|
||||
print("🔍 Laufzeit-Verifikation des Mindnet-Services")
|
||||
print("=" * 80)
|
||||
|
||||
# 1. Prüfe Health-Endpoint
|
||||
print("\n1. Prüfe Service-Status (Health-Check):")
|
||||
try:
|
||||
response = requests.get("http://localhost:8001/healthz", timeout=5)
|
||||
if response.status_code == 200:
|
||||
health_data = response.json()
|
||||
print(f" ✅ Service läuft")
|
||||
print(f" -> Status: {health_data.get('status')}")
|
||||
print(f" -> Version: {health_data.get('version')}")
|
||||
print(f" -> Prefix: {health_data.get('prefix')}")
|
||||
print(f" -> Qdrant: {health_data.get('qdrant')}")
|
||||
|
||||
# WP-24c v4.5.10: Prüfe EdgeDTO-Version im laufenden Service
|
||||
edge_dto_supports = health_data.get('edge_dto_supports_callout')
|
||||
if edge_dto_supports is not None:
|
||||
if edge_dto_supports:
|
||||
print(f" ✅ Service unterstützt 'explicit:callout' (zur Laufzeit verifiziert)")
|
||||
else:
|
||||
print(f" ❌ Service unterstützt NICHT 'explicit:callout' (alte Version im Speicher!)")
|
||||
print(f" -> Aktion erforderlich: Cache leeren und Service neu starten")
|
||||
else:
|
||||
print(f" ⚠️ Health-Check meldet keine EdgeDTO-Version (alte API-Version?)")
|
||||
else:
|
||||
print(f" ⚠️ Service antwortet mit Status {response.status_code}")
|
||||
print(f" -> Response: {response.text[:200]}")
|
||||
except requests.exceptions.ConnectionError:
|
||||
print(" ❌ Service nicht erreichbar (läuft er auf Port 8001?)")
|
||||
print(" -> Tipp: sudo systemctl status mindnet-prod")
|
||||
sys.exit(1)
|
||||
except Exception as e:
|
||||
print(f" ❌ Fehler beim Health-Check: {e}")
|
||||
sys.exit(1)
|
||||
|
||||
# 2. Test: Versuche eine Test-Query mit explicit:callout Edge
|
||||
print("\n2. Test: Retrieval mit explicit:callout Edge:")
|
||||
print(" -> Sende Test-Query an /chat/...")
|
||||
print(" -> Hinweis: Timeout nach 30s ist möglich bei LLM-Calls")
|
||||
try:
|
||||
test_query = {
|
||||
"message": "Test query für EdgeDTO-Verifikation",
|
||||
"explain": False
|
||||
}
|
||||
# WP-24c: Router ist mit prefix="/chat" eingebunden, Endpoint ist "/"
|
||||
# Erhöhter Timeout für LLM-Calls (können länger dauern)
|
||||
response = requests.post(
|
||||
"http://localhost:8001/chat/",
|
||||
json=test_query,
|
||||
timeout=60 # Erhöht von 30 auf 60 Sekunden
|
||||
)
|
||||
|
||||
if response.status_code == 200:
|
||||
result = response.json()
|
||||
print(f" ✅ Query erfolgreich verarbeitet")
|
||||
print(f" -> Antwort-Länge: {len(result.get('response', ''))} Zeichen")
|
||||
|
||||
# Prüfe Logs auf EdgeDTO-Fehler (wenn verfügbar)
|
||||
if 'warnings' in result or 'errors' in result:
|
||||
warnings = result.get('warnings', [])
|
||||
errors = result.get('errors', [])
|
||||
if warnings:
|
||||
print(f" ⚠️ Warnings: {warnings}")
|
||||
if errors:
|
||||
print(f" ❌ Errors: {errors}")
|
||||
else:
|
||||
print(f" ⚠️ Query fehlgeschlagen mit Status {response.status_code}")
|
||||
print(f" -> Response: {response.text[:500]}")
|
||||
|
||||
except requests.exceptions.ReadTimeout:
|
||||
print(f" ⚠️ Query-Timeout (Service antwortet nicht innerhalb von 60s)")
|
||||
print(f" -> Mögliche Ursachen:")
|
||||
print(f" - LLM-Call dauert länger als erwartet")
|
||||
print(f" - Service hängt bei der Verarbeitung")
|
||||
print(f" -> Tipp: Prüfe Service-Logs mit: sudo journalctl -u mindnet-prod -n 50")
|
||||
print(f" -> WICHTIG: EdgeDTO-Problem ist gelöst (siehe Punkt 1)")
|
||||
except Exception as e:
|
||||
print(f" ⚠️ Fehler bei Test-Query: {e}")
|
||||
print(f" -> WICHTIG: EdgeDTO-Problem ist gelöst (siehe Punkt 1)")
|
||||
# Kein vollständiger Traceback für Timeouts, da diese erwartbar sind
|
||||
|
||||
# 3. Direkte Code-Verifikation (falls Service-Code zugänglich)
|
||||
print("\n3. Code-Verifikation (lokale Dateien):")
|
||||
try:
|
||||
from app.models.dto import EdgeDTO
|
||||
import inspect
|
||||
|
||||
source = inspect.getsource(EdgeDTO)
|
||||
if "explicit:callout" in source:
|
||||
print(" ✅ Lokaler Code unterstützt 'explicit:callout'")
|
||||
print(f" -> Datei: {inspect.getfile(EdgeDTO)}")
|
||||
|
||||
# Prüfe, ob die Datei aktuell ist
|
||||
dto_file = Path(inspect.getfile(EdgeDTO))
|
||||
if dto_file.exists():
|
||||
import time
|
||||
mtime = dto_file.stat().st_mtime
|
||||
mtime_str = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(mtime))
|
||||
print(f" -> Letzte Änderung: {mtime_str}")
|
||||
else:
|
||||
print(" ❌ Lokaler Code unterstützt NICHT 'explicit:callout'")
|
||||
|
||||
# Test-Erstellung
|
||||
test_edge = EdgeDTO(
|
||||
id="test", kind="test", source="test", target="test",
|
||||
weight=1.0, provenance="explicit:callout"
|
||||
)
|
||||
print(" ✅ EdgeDTO mit 'explicit:callout' erfolgreich erstellt!")
|
||||
|
||||
except Exception as e:
|
||||
print(f" ❌ Fehler bei Code-Verifikation: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
|
||||
# 4. Prüfe Python-Cache
|
||||
print("\n4. Prüfe Python-Cache:")
|
||||
try:
|
||||
dto_cache_dir = project_root / "app" / "models" / "__pycache__"
|
||||
if dto_cache_dir.exists():
|
||||
cache_files = list(dto_cache_dir.glob("dto*.pyc"))
|
||||
if cache_files:
|
||||
print(f" ⚠️ Gefunden: {len(cache_files)} Cache-Datei(en) in app/models/__pycache__")
|
||||
print(f" -> Tipp: Cache leeren mit: find . -type d -name __pycache__ -exec rm -r {{}} +")
|
||||
else:
|
||||
print(" ✅ Keine Cache-Dateien gefunden")
|
||||
else:
|
||||
print(" ✅ Kein Cache-Verzeichnis vorhanden")
|
||||
except Exception as e:
|
||||
print(f" ⚠️ Fehler bei Cache-Prüfung: {e}")
|
||||
|
||||
# 5. Empfehlungen
|
||||
print("\n5. Empfehlungen:")
|
||||
print(" 📋 Wenn der Service noch eine alte Version verwendet:")
|
||||
print(" 1. Python-Cache leeren:")
|
||||
print(" find . -type d -name __pycache__ -exec rm -r {} + 2>/dev/null || true")
|
||||
print(" find . -name '*.pyc' -delete")
|
||||
print(" 2. Service neu starten:")
|
||||
print(" sudo systemctl restart mindnet-prod")
|
||||
print(" 3. Status prüfen:")
|
||||
print(" sudo systemctl status mindnet-prod")
|
||||
print(" 4. Logs prüfen:")
|
||||
print(" sudo journalctl -u mindnet-prod -f")
|
||||
|
||||
print("\n" + "=" * 80)
|
||||
@@ -0,0 +1,78 @@
|
||||
"""
|
||||
FILE: tests/test_container_appenv.py
|
||||
DESCRIPTION: Prüft deploy/appenv.py: Aus der unveränderten .env der systemd-Instanz
|
||||
werden Vault-Mount und Präfix so abgeleitet, dass der Container dieselbe
|
||||
Konfiguration nutzt; die Container-Datei darf nichts davon überschreiben.
|
||||
"""
|
||||
import importlib.util
|
||||
import shlex
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
DEPLOY = Path(__file__).resolve().parents[1] / "deploy"
|
||||
_spec = importlib.util.spec_from_file_location("mindnet_appenv", DEPLOY / "appenv.py")
|
||||
appenv = importlib.util.module_from_spec(_spec)
|
||||
_spec.loader.exec_module(appenv)
|
||||
|
||||
APP_ENV = "/home/llmadmin/mindnet_dev/.env"
|
||||
|
||||
|
||||
def _files(tmp_path, app_text, container_text="MINDNET_UI_PORT=8512\n"):
|
||||
app = tmp_path / "app.env"
|
||||
app.write_text(app_text, encoding="utf-8")
|
||||
container = tmp_path / "container.env"
|
||||
container.write_text(container_text, encoding="utf-8")
|
||||
return str(app), str(container)
|
||||
|
||||
|
||||
def test_parse_handles_export_quotes_and_comments(tmp_path):
|
||||
app, _ = _files(tmp_path, '# Kommentar\nexport A=1\nB="mit # Raute"\nC=wert # Kommentar\nD=\n')
|
||||
assert appenv.parse(app) == {"A": "1", "B": "mit # Raute", "C": "wert", "D": ""}
|
||||
|
||||
|
||||
@pytest.mark.parametrize("root, host, target", [
|
||||
("./vault", "/home/llmadmin/mindnet_dev/vault", "/app/vault"),
|
||||
("vault_dev", "/home/llmadmin/mindnet_dev/vault_dev", "/app/vault_dev"),
|
||||
("../shared/vault", "/home/llmadmin/shared/vault", "/shared/vault"),
|
||||
("/mnt/nas/vault/", "/mnt/nas/vault", "/mnt/nas/vault"),
|
||||
])
|
||||
def test_vault_mount_points_where_the_app_looks(root, host, target):
|
||||
# Relativ: systemd löst gegen WorkingDirectory (= Ordner der .env) auf, der Container gegen /app.
|
||||
assert appenv.vault_mount(APP_ENV, {"MINDNET_VAULT_ROOT": root}) == (host, target)
|
||||
|
||||
|
||||
def test_vault_mount_uses_app_default_when_unset():
|
||||
assert appenv.vault_mount(APP_ENV, {}) == ("/home/llmadmin/mindnet_dev/vault_master", "/app/vault_master")
|
||||
|
||||
|
||||
def test_derive_takes_prefix_from_systemd_env(tmp_path):
|
||||
app, container = _files(tmp_path, "COLLECTION_PREFIX=mindnet_dev\nMINDNET_VAULT_ROOT=/srv/vault\n")
|
||||
derived = appenv.derive(app, container)
|
||||
assert derived["MINDNET_EXPECTED_PREFIX"] == "mindnet_dev"
|
||||
assert derived["MINDNET_VAULT_HOST_PATH"] == derived["MINDNET_VAULT_TARGET"] == "/srv/vault"
|
||||
|
||||
|
||||
def test_derive_falls_back_to_app_default_prefix(tmp_path):
|
||||
app, container = _files(tmp_path, "MINDNET_VAULT_ROOT=/srv/vault\n")
|
||||
assert appenv.derive(app, container)["MINDNET_EXPECTED_PREFIX"] == "mindnet"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("key", ["COLLECTION_PREFIX", "MINDNET_VAULT_ROOT", "OPENROUTER_API_KEY", "QDRANT_URL"])
|
||||
def test_container_env_must_not_override_app_config(tmp_path, key):
|
||||
app, container = _files(tmp_path, "COLLECTION_PREFIX=mindnet_dev\n", f"MINDNET_UI_PORT=8512\n{key}=x\n")
|
||||
with pytest.raises(appenv.AppEnvError, match=key):
|
||||
appenv.derive(app, container)
|
||||
|
||||
|
||||
def test_main_prints_shell_safe_assignments(tmp_path, capsys):
|
||||
app, container = _files(tmp_path, "COLLECTION_PREFIX=mindnet_dev\nMINDNET_VAULT_ROOT=/srv/my vault\n")
|
||||
assert appenv.main(["appenv.py", app, container]) == 0
|
||||
lines = capsys.readouterr().out.splitlines()
|
||||
parsed = dict(shlex.split(line)[0].split("=", 1) for line in lines)
|
||||
assert parsed["MINDNET_VAULT_HOST_PATH"] == "/srv/my vault"
|
||||
|
||||
|
||||
def test_main_reports_missing_file(tmp_path, capsys):
|
||||
assert appenv.main(["appenv.py", str(tmp_path / "fehlt.env"), str(tmp_path / "auch.env")]) == 1
|
||||
assert "appenv:" in capsys.readouterr().err
|
||||
@@ -0,0 +1,258 @@
|
||||
"""
|
||||
FILE: tests/test_container_connectivity.py
|
||||
DESCRIPTION: Prüft die Erreichbarkeitsprüfungen der Container-Bereitstellung gegen einen
|
||||
lokalen Fake-Server (Ollama, Qdrant, Mindnet-API, Streamlit-UI):
|
||||
- deploy/entrypoint.py: preflight --live (Dienste, Modelle, Dimensionen)
|
||||
- deploy/smoke.py: Smoke-Test nach dem Start
|
||||
Läuft ohne Docker und ohne echte Dienste (auch mit --network none).
|
||||
"""
|
||||
import importlib.util
|
||||
import json
|
||||
import threading
|
||||
import urllib.error
|
||||
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
|
||||
DEPLOY = Path(__file__).resolve().parents[1] / "deploy"
|
||||
|
||||
|
||||
def _load(name):
|
||||
spec = importlib.util.spec_from_file_location(f"mindnet_{name}", DEPLOY / f"{name}.py")
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
ep = _load("entrypoint")
|
||||
smoke = _load("smoke")
|
||||
|
||||
|
||||
class FakeServices(ThreadingHTTPServer):
|
||||
"""Ein Server für alle Dienste; Zustand pro Test über Attribute steuerbar."""
|
||||
|
||||
def __init__(self):
|
||||
super().__init__(("127.0.0.1", 0), _Handler)
|
||||
self.models = ["nomic-embed-text:latest", "phi3:mini"]
|
||||
self.embedding_dim = 768
|
||||
self.collections = {"mindnet_dev_notes": 768, "mindnet_dev_chunks": 768}
|
||||
self.api_key = None
|
||||
self.seen_headers = []
|
||||
self.health = {"status": "ok", "prefix": "mindnet_dev"}
|
||||
self.vector_size = 768
|
||||
self.counts = {"notes": 12, "chunks": 80, "edges": 40}
|
||||
self.ui_body = b"ok"
|
||||
|
||||
@property
|
||||
def url(self):
|
||||
return f"http://127.0.0.1:{self.server_address[1]}"
|
||||
|
||||
|
||||
class _Handler(BaseHTTPRequestHandler):
|
||||
def log_message(self, *args):
|
||||
pass
|
||||
|
||||
def _send(self, status, body):
|
||||
data = body if isinstance(body, bytes) else json.dumps(body).encode()
|
||||
self.send_response(status)
|
||||
self.send_header("Content-Length", str(len(data)))
|
||||
self.end_headers()
|
||||
self.wfile.write(data)
|
||||
|
||||
def do_POST(self):
|
||||
srv = self.server
|
||||
self.rfile.read(int(self.headers.get("Content-Length") or 0))
|
||||
if self.path == "/api/embeddings":
|
||||
return self._send(200, {"embedding": [0.1] * srv.embedding_dim})
|
||||
self._send(404, {})
|
||||
|
||||
def do_GET(self):
|
||||
srv = self.server
|
||||
srv.seen_headers.append(dict(self.headers))
|
||||
if self.path.startswith("/collections") and srv.api_key and self.headers.get("api-key") != srv.api_key:
|
||||
return self._send(401, {})
|
||||
if self.path == "/api/tags":
|
||||
return self._send(200, {"models": [{"name": m} for m in srv.models]})
|
||||
if self.path == "/collections":
|
||||
return self._send(200, {"result": {"collections": []}})
|
||||
if self.path.startswith("/collections/"):
|
||||
name = self.path.rsplit("/", 1)[1]
|
||||
if name not in srv.collections:
|
||||
return self._send(404, {})
|
||||
size = srv.collections[name]
|
||||
return self._send(200, {"result": {"config": {"params": {"vectors": {"size": size}}}}})
|
||||
if self.path == "/healthz":
|
||||
return self._send(200, srv.health)
|
||||
if self.path == "/admin/stats":
|
||||
collections = {k: {"name": f"mindnet_dev_{k}", "count": v} for k, v in srv.counts.items()}
|
||||
return self._send(200, {"collections": collections, "config": {"vector_size": srv.vector_size}})
|
||||
if self.path == "/_stcore/health":
|
||||
return self._send(200, srv.ui_body)
|
||||
self._send(404, {})
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def services():
|
||||
srv = FakeServices()
|
||||
thread = threading.Thread(target=srv.serve_forever, daemon=True)
|
||||
thread.start()
|
||||
yield srv
|
||||
srv.shutdown()
|
||||
srv.server_close()
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def live_env(monkeypatch, services):
|
||||
for key in ("QDRANT_API_KEY", "MINDNET_EXPECTED_VECTOR_DIM", "MINDNET_EXPECTED_EMBEDDING_MODEL"):
|
||||
monkeypatch.delenv(key, raising=False)
|
||||
monkeypatch.chdir(DEPLOY.parent)
|
||||
monkeypatch.setenv("MINDNET_OLLAMA_URL", services.url)
|
||||
monkeypatch.setenv("QDRANT_URL", services.url)
|
||||
monkeypatch.setenv("COLLECTION_PREFIX", "mindnet_dev")
|
||||
monkeypatch.setenv("MINDNET_LLM_MODEL", "phi3:mini")
|
||||
return monkeypatch
|
||||
|
||||
|
||||
def _closed_port_url():
|
||||
srv = ThreadingHTTPServer(("127.0.0.1", 0), BaseHTTPRequestHandler)
|
||||
port = srv.server_address[1]
|
||||
srv.server_close()
|
||||
return f"http://127.0.0.1:{port}"
|
||||
|
||||
|
||||
# --- Dienst-URLs (statisch) -------------------------------------------------------------
|
||||
|
||||
@pytest.mark.parametrize("url", ["", "http://127.0.0.1:11434", "http://localhost:6333", "http://0.0.0.0:6333"])
|
||||
def test_service_urls_reject_missing_or_container_local(monkeypatch, url):
|
||||
monkeypatch.setenv("QDRANT_URL", "http://qdrant:6333")
|
||||
monkeypatch.setenv("MINDNET_OLLAMA_URL", url)
|
||||
with pytest.raises(ep.PreflightError, match="MINDNET_OLLAMA_URL"):
|
||||
ep.check_service_urls()
|
||||
|
||||
|
||||
def test_service_urls_accept_host_gateway_and_compose_service(monkeypatch):
|
||||
monkeypatch.setenv("MINDNET_OLLAMA_URL", "http://host.docker.internal:11434")
|
||||
monkeypatch.setenv("QDRANT_URL", "http://qdrant:6333")
|
||||
ep.check_service_urls()
|
||||
|
||||
|
||||
def test_required_models_come_from_ollama_profiles_and_chat_model(live_env):
|
||||
live_env.setenv("MINDNET_LLM_MODEL", "llama3:8b")
|
||||
assert {"nomic-embed-text", "phi3:mini", "llama3:8b"} <= ep.required_ollama_models()
|
||||
|
||||
|
||||
# --- preflight --live ----------------------------------------------------------------------
|
||||
|
||||
def test_live_passes_when_everything_matches(live_env, capsys):
|
||||
ep.check_live()
|
||||
out = capsys.readouterr().out
|
||||
assert "Ollama erreichbar" in out and "Qdrant erreichbar" in out
|
||||
|
||||
|
||||
def test_live_reports_missing_ollama_model(live_env, services):
|
||||
services.models = ["nomic-embed-text:latest"]
|
||||
with pytest.raises(ep.PreflightError, match="phi3:mini"):
|
||||
ep.check_live()
|
||||
|
||||
|
||||
def test_live_does_not_accept_other_tag_as_latest(live_env, services):
|
||||
services.models = ["nomic-embed-text:v1.5", "phi3:mini"]
|
||||
with pytest.raises(ep.PreflightError, match="nomic-embed-text"):
|
||||
ep.check_live()
|
||||
|
||||
|
||||
def test_live_rejects_wrong_embedding_dimension(live_env, services):
|
||||
services.embedding_dim = 384
|
||||
with pytest.raises(ep.PreflightError, match="384 Dimensionen"):
|
||||
ep.check_live()
|
||||
|
||||
|
||||
def test_live_rejects_wrong_collection_dimension(live_env, services):
|
||||
services.collections["mindnet_dev_chunks"] = 384
|
||||
with pytest.raises(ep.PreflightError, match="mindnet_dev_chunks"):
|
||||
ep.check_live()
|
||||
|
||||
|
||||
def test_live_accepts_missing_collections(live_env, services, capsys):
|
||||
services.collections = {}
|
||||
ep.check_live()
|
||||
assert "existiert noch nicht" in capsys.readouterr().out
|
||||
|
||||
|
||||
def test_live_sends_qdrant_api_key(live_env, services):
|
||||
services.api_key = "secret"
|
||||
with pytest.raises(ep.PreflightError, match="HTTP 401"):
|
||||
ep.check_live()
|
||||
live_env.setenv("QDRANT_API_KEY", "secret")
|
||||
ep.check_live()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("var", ["MINDNET_OLLAMA_URL", "QDRANT_URL"])
|
||||
def test_live_unreachable_service_is_a_clear_error(live_env, var):
|
||||
live_env.setenv(var, _closed_port_url())
|
||||
with pytest.raises(ep.PreflightError, match="nicht erreichbar"):
|
||||
ep.check_live()
|
||||
|
||||
|
||||
def test_unreachable_host_gateway_hints_at_loopback_binding(monkeypatch):
|
||||
def refuse(*args, **kwargs):
|
||||
raise urllib.error.URLError(ConnectionRefusedError(111, "Connection refused"))
|
||||
|
||||
monkeypatch.setattr(ep.urllib.request, "urlopen", refuse)
|
||||
with pytest.raises(ep.PreflightError, match="nur an 127.0.0.1"):
|
||||
ep._fetch_json("http://host.docker.internal:11434/api/tags")
|
||||
|
||||
|
||||
def test_preflight_live_exits_1_instead_of_traceback(live_env, monkeypatch, tmp_path):
|
||||
root = tmp_path / "vault"
|
||||
(root / "_system" / "dictionary").mkdir(parents=True)
|
||||
(root / "_system" / "dictionary" / "edge_vocabulary.md").write_text("x", encoding="utf-8")
|
||||
for key, value in {"MINDNET_ENV": "dev", "VECTOR_DIM": "768", "MINDNET_VAULT_ROOT": str(root),
|
||||
"OPENROUTER_API_KEY": "", "GOOGLE_API_KEY": "", "MINDNET_EMBEDDING_MODEL": ""}.items():
|
||||
monkeypatch.setenv(key, value)
|
||||
monkeypatch.setattr(ep, "_is_read_only_mount", lambda path: True)
|
||||
monkeypatch.setattr(ep, "check_service_urls", lambda: None) # Fake-Server läuft auf 127.0.0.1
|
||||
assert ep.main(["entrypoint.py", "preflight", "--live"]) == 0
|
||||
monkeypatch.setenv("QDRANT_URL", _closed_port_url())
|
||||
assert ep.main(["entrypoint.py", "preflight", "--live"]) == 1
|
||||
|
||||
|
||||
# --- smoke.py ---------------------------------------------------------------------------------
|
||||
|
||||
def _smoke(services, **kwargs):
|
||||
return smoke.run(services.url, services.url, "mindnet_dev", attempts=1, **kwargs)
|
||||
|
||||
|
||||
def test_smoke_ok(services, capsys):
|
||||
assert _smoke(services) == 0
|
||||
assert "smoke: OK" in capsys.readouterr().out
|
||||
|
||||
|
||||
@pytest.mark.parametrize("change", [
|
||||
lambda s: s.health.update(prefix="mindnet"),
|
||||
lambda s: s.health.update(status="degraded"),
|
||||
lambda s: setattr(s, "vector_size", 384),
|
||||
lambda s: setattr(s, "ui_body", b"starting"),
|
||||
])
|
||||
def test_smoke_fails_on_wrong_state(services, change):
|
||||
change(services)
|
||||
assert _smoke(services) == 1
|
||||
|
||||
|
||||
def test_smoke_unreachable_api():
|
||||
url = _closed_port_url()
|
||||
assert smoke.run(url, url, "mindnet_dev", attempts=1) == 1
|
||||
|
||||
|
||||
def test_smoke_missing_collection_warns_in_dev_and_fails_with_require_data(services, capsys):
|
||||
services.counts["edges"] = -1
|
||||
assert _smoke(services) == 0
|
||||
assert "WARNUNG" in capsys.readouterr().out
|
||||
assert _smoke(services, require_data=True) == 1
|
||||
|
||||
|
||||
def test_smoke_require_data_rejects_empty_notes(services):
|
||||
services.counts["notes"] = 0
|
||||
assert _smoke(services) == 0
|
||||
assert _smoke(services, require_data=True) == 1
|
||||
@@ -0,0 +1,318 @@
|
||||
"""
|
||||
FILE: tests/test_container_preflight.py
|
||||
DESCRIPTION: Prüft Container-Preflight (deploy/entrypoint.py) und statisch die
|
||||
Sicherheitszusagen der Compose-/Docker-Dateien. Läuft ohne Docker.
|
||||
"""
|
||||
import importlib.util
|
||||
import re
|
||||
from pathlib import Path
|
||||
|
||||
import pytest
|
||||
import yaml
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
DEPLOY = ROOT / "deploy"
|
||||
SYSTEMD_PORTS = {8001, 8002, 8501, 8502}
|
||||
# WorkingDirectory der systemd-Units (llm-node), deren .env der Container unverändert liest.
|
||||
SYSTEMD_ENV_FILES = {"dev": "/home/llmadmin/mindnet_dev/.env", "prod": "/home/llmadmin/mindnet/.env"}
|
||||
|
||||
|
||||
def _load_deploy_module(name):
|
||||
spec = importlib.util.spec_from_file_location(f"mindnet_{name}", DEPLOY / f"{name}.py")
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
ep = _load_deploy_module("entrypoint")
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def env(monkeypatch):
|
||||
for key in ("MINDNET_ENV", "COLLECTION_PREFIX", "VECTOR_DIM", "MINDNET_EMBEDDING_MODEL",
|
||||
"OPENROUTER_API_KEY", "GOOGLE_API_KEY", "MINDNET_ALLOW_CLOUD_EGRESS",
|
||||
"MINDNET_VAULT_ROOT", "MINDNET_VAULT_SENTINEL", "MINDNET_VAULT_READONLY",
|
||||
"MINDNET_VAULT_REQUIRED", "MINDNET_EXPECTED_VECTOR_DIM"):
|
||||
monkeypatch.delenv(key, raising=False)
|
||||
monkeypatch.chdir(ROOT)
|
||||
return monkeypatch
|
||||
|
||||
|
||||
# --- Umgebung und Präfix ---------------------------------------------------------
|
||||
|
||||
@pytest.mark.parametrize("menv, prefix", [("", "mindnet"), ("staging", "mindnet"), ("prod", ""),
|
||||
("dev", "mindnet"), ("prod", "mindnet_dev")])
|
||||
def test_environment_rejects_ambiguous_setups(env, menv, prefix):
|
||||
env.setenv("MINDNET_ENV", menv)
|
||||
env.setenv("COLLECTION_PREFIX", prefix)
|
||||
with pytest.raises(ep.PreflightError):
|
||||
ep.check_environment()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("menv, prefix", [("dev", "mindnet_dev"), ("prod", "mindnet")])
|
||||
def test_environment_accepts_explicit_setups(env, menv, prefix):
|
||||
env.setenv("MINDNET_ENV", menv)
|
||||
env.setenv("COLLECTION_PREFIX", prefix)
|
||||
assert ep.check_environment() == menv
|
||||
|
||||
|
||||
# --- Embeddings: keine stille Rückkehr zu 384 Dimensionen -----------------------
|
||||
|
||||
@pytest.mark.parametrize("dim", [None, "384", "3072"])
|
||||
def test_embeddings_reject_wrong_or_missing_dim(env, dim):
|
||||
if dim:
|
||||
env.setenv("VECTOR_DIM", dim)
|
||||
with pytest.raises(ep.PreflightError, match="VECTOR_DIM"):
|
||||
ep.check_embeddings()
|
||||
|
||||
|
||||
def test_embeddings_accept_repository_profile(env):
|
||||
env.setenv("VECTOR_DIM", "768")
|
||||
ep.check_embeddings()
|
||||
|
||||
|
||||
def test_embeddings_reject_minilm_override(env):
|
||||
env.setenv("VECTOR_DIM", "768")
|
||||
env.setenv("MINDNET_EMBEDDING_MODEL", "sentence-transformers/all-MiniLM-L6-v2")
|
||||
with pytest.raises(ep.PreflightError, match="MINDNET_EMBEDDING_MODEL"):
|
||||
ep.check_embeddings()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("profile", [
|
||||
{"provider": "ollama", "model": "all-minilm", "dimensions": 384},
|
||||
{"provider": "ollama", "model": "nomic-embed-text", "dimensions": 384},
|
||||
{"provider": "ollama", "model": "nomic-embed-text"},
|
||||
])
|
||||
def test_embeddings_reject_bad_profile(env, tmp_path, profile):
|
||||
env.setenv("VECTOR_DIM", "768")
|
||||
path = tmp_path / "profiles.yaml"
|
||||
path.write_text(yaml.safe_dump({"profiles": {"embedding_expert": profile}}), encoding="utf-8")
|
||||
with pytest.raises(ep.PreflightError, match="embedding_expert"):
|
||||
ep.check_embeddings(str(path))
|
||||
|
||||
|
||||
# --- Cloud-Egress ------------------------------------------------------------------
|
||||
|
||||
def test_cloud_keys_require_explicit_ack(env):
|
||||
env.setenv("OPENROUTER_API_KEY", "sk-test")
|
||||
with pytest.raises(ep.PreflightError, match="MINDNET_ALLOW_CLOUD_EGRESS"):
|
||||
ep.check_cloud_egress()
|
||||
env.setenv("MINDNET_ALLOW_CLOUD_EGRESS", "true")
|
||||
ep.check_cloud_egress()
|
||||
|
||||
|
||||
def test_no_cloud_keys_needs_no_ack(env):
|
||||
ep.check_cloud_egress()
|
||||
|
||||
|
||||
# --- Vault / NAS -----------------------------------------------------------------------
|
||||
|
||||
def _vault(tmp_path, with_content=True):
|
||||
root = tmp_path / "vault"
|
||||
root.mkdir()
|
||||
if with_content:
|
||||
(root / "notiz.md").write_text("# Notiz", encoding="utf-8")
|
||||
return root
|
||||
|
||||
|
||||
def test_vault_missing_directory(env, tmp_path):
|
||||
env.setenv("MINDNET_VAULT_ROOT", str(tmp_path / "nope"))
|
||||
with pytest.raises(ep.PreflightError, match="fehlt"):
|
||||
ep.check_vault()
|
||||
|
||||
|
||||
def test_vault_empty_mountpoint_is_detected(env, tmp_path):
|
||||
# Ausgefallenes NAS: Mountpunkt existiert, ist aber leer.
|
||||
env.setenv("MINDNET_VAULT_ROOT", str(_vault(tmp_path, with_content=False)))
|
||||
with pytest.raises(ep.PreflightError, match="leer"):
|
||||
ep.check_vault()
|
||||
|
||||
|
||||
def test_vault_needs_no_specific_file_by_default(env, tmp_path):
|
||||
# Wie systemd: jeder Vault-Aufbau ist zulässig (vault_master hat kein _system/).
|
||||
env.setenv("MINDNET_VAULT_ROOT", str(_vault(tmp_path)))
|
||||
env.setattr(ep, "_is_read_only_mount", lambda path: True)
|
||||
ep.check_vault()
|
||||
|
||||
|
||||
def test_vault_optional_sentinel_is_enforced(env, tmp_path):
|
||||
env.setenv("MINDNET_VAULT_ROOT", str(_vault(tmp_path)))
|
||||
env.setenv("MINDNET_VAULT_SENTINEL", "_system/dictionary/edge_vocabulary.md")
|
||||
with pytest.raises(ep.PreflightError, match="Sentinel"):
|
||||
ep.check_vault()
|
||||
|
||||
|
||||
def test_vault_must_be_read_only(env, tmp_path):
|
||||
env.setenv("MINDNET_VAULT_ROOT", str(_vault(tmp_path)))
|
||||
env.setattr(ep, "_is_read_only_mount", lambda path: False)
|
||||
with pytest.raises(ep.PreflightError, match="schreibgeschützt"):
|
||||
ep.check_vault()
|
||||
env.setattr(ep, "_is_read_only_mount", lambda path: True)
|
||||
ep.check_vault()
|
||||
|
||||
|
||||
def test_read_only_check_fails_closed_without_statvfs(env, tmp_path):
|
||||
env.delattr(ep.os, "statvfs", raising=False)
|
||||
assert ep._is_read_only_mount(tmp_path) is False
|
||||
|
||||
|
||||
def test_unknown_mode_is_rejected():
|
||||
assert ep.main(["entrypoint.py", "shell"]) == 2
|
||||
|
||||
|
||||
# --- Statische Prüfung der Deployment-Dateien ---------------------------------------
|
||||
|
||||
def _compose(name):
|
||||
return yaml.safe_load((DEPLOY / name).read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
def _host_port(mapping):
|
||||
m = re.search(r":(?:\$\{[A-Z_]+:-)?(\d+)\}?:\d+$", mapping)
|
||||
return int(m.group(1))
|
||||
|
||||
|
||||
COMPOSE = {"dev": _compose("compose.dev.yml"), "prod": _compose("compose.prod.yml")}
|
||||
APP_SERVICES = ("api", "ui")
|
||||
|
||||
|
||||
def test_compose_projects_are_separate():
|
||||
assert COMPOSE["dev"]["name"] == "mindnet-dev"
|
||||
assert COMPOSE["prod"]["name"] == "mindnet-prod"
|
||||
assert set(COMPOSE["dev"]["networks"]).isdisjoint(COMPOSE["prod"]["networks"])
|
||||
|
||||
|
||||
def test_compose_ports_do_not_collide():
|
||||
ports = {e: {_host_port(p) for s in c["services"].values() for p in s.get("ports", [])}
|
||||
for e, c in COMPOSE.items()}
|
||||
assert ports["dev"].isdisjoint(ports["prod"])
|
||||
assert not (ports["dev"] | ports["prod"]) & SYSTEMD_PORTS
|
||||
|
||||
|
||||
@pytest.mark.parametrize("envname", ["dev", "prod"])
|
||||
def test_compose_app_services_hardened(envname):
|
||||
for name in APP_SERVICES:
|
||||
svc = COMPOSE[envname]["services"][name]
|
||||
assert svc["read_only"] is True
|
||||
assert svc["cap_drop"] == ["ALL"]
|
||||
assert "no-new-privileges:true" in svc["security_opt"]
|
||||
assert svc["environment"]["VECTOR_DIM"] == "768"
|
||||
assert svc["environment"]["MINDNET_VAULT_READONLY"] == "true"
|
||||
assert svc["healthcheck"]["test"][-1] == name
|
||||
|
||||
|
||||
@pytest.mark.parametrize("envname", ["dev", "prod"])
|
||||
def test_compose_vault_is_read_only_bind_without_autocreate(envname):
|
||||
mounts = [v for v in COMPOSE[envname]["services"]["api"]["volumes"]
|
||||
if isinstance(v, dict) and v.get("type") == "bind"]
|
||||
assert len(mounts) == 1
|
||||
assert mounts[0]["target"].startswith("${MINDNET_VAULT_TARGET:?") # aus der systemd-.env abgeleitet
|
||||
assert mounts[0]["read_only"] is True
|
||||
assert mounts[0]["bind"]["create_host_path"] is False
|
||||
assert not [v for v in COMPOSE[envname]["services"]["ui"]["volumes"] if isinstance(v, dict)]
|
||||
|
||||
|
||||
@pytest.mark.parametrize("envname", ["dev", "prod"])
|
||||
def test_compose_api_defaults_to_loopback(envname):
|
||||
assert all(p.startswith("${MINDNET_API_BIND:-127.0.0.1}:") for p in COMPOSE[envname]["services"]["api"]["ports"])
|
||||
|
||||
|
||||
@pytest.mark.parametrize("envname", ["dev", "prod"])
|
||||
def test_compose_uses_existing_host_services_and_app_config(envname):
|
||||
# Wie systemd: gemeinsame Host-Qdrant und Host-Ollama; Präfix/Vault aus der systemd-.env.
|
||||
assert set(COMPOSE[envname]["services"]) == set(APP_SERVICES)
|
||||
for name in APP_SERVICES:
|
||||
env = COMPOSE[envname]["services"][name]["environment"]
|
||||
assert env["MINDNET_ENV"] == envname
|
||||
assert env["QDRANT_URL"] == "http://host.docker.internal:6333"
|
||||
assert env["MINDNET_OLLAMA_URL"] == "http://host.docker.internal:11434"
|
||||
assert not {"COLLECTION_PREFIX", "MINDNET_VAULT_ROOT", "MINDNET_VOCAB_PATH"} & set(env)
|
||||
|
||||
|
||||
def test_dockerfile_pinned_and_non_root():
|
||||
text = (DEPLOY / "Dockerfile").read_text(encoding="utf-8")
|
||||
assert re.search(r"ARG PYTHON_IMAGE=python:3\.12-slim-bookworm@sha256:[0-9a-f]{64}", text)
|
||||
runtime = text.split("AS runtime", 1)[1].split("AS test", 1)[0]
|
||||
assert "USER mindnet:mindnet" in runtime
|
||||
assert "--require-hashes" in text
|
||||
|
||||
|
||||
def test_lock_excludes_torch_and_minilm_and_is_hashed():
|
||||
lock = (DEPLOY / "requirements.lock").read_text(encoding="utf-8")
|
||||
pins = re.findall(r"^([a-z0-9][a-z0-9._-]*)==", lock, re.M)
|
||||
assert pins and not {"torch", "sentence-transformers", "transformers"} & set(pins)
|
||||
entries = re.split(r"\n(?=[a-z0-9])", lock.strip())
|
||||
assert all("--hash=sha256:" in e for e in entries if re.match(r"[a-z0-9]", e))
|
||||
|
||||
|
||||
def test_dockerignore_is_allowlist_without_env_files():
|
||||
lines = [l.strip() for l in (ROOT / ".dockerignore").read_text(encoding="utf-8").splitlines()
|
||||
if l.strip() and not l.startswith("#")]
|
||||
assert lines[0] == "**"
|
||||
assert "config/*.env" in lines and "deploy/env/*.env" in lines
|
||||
assert not any(l.startswith("!") and ("vault" in l or ".env" in l) for l in lines)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("envname", ["dev", "prod"])
|
||||
def test_container_env_example_has_only_container_keys(envname):
|
||||
appenv = _load_deploy_module("appenv")
|
||||
values = appenv.parse(str(DEPLOY / "env" / f"{envname}.env.example"))
|
||||
assert set(values) <= appenv.CONTAINER_KEYS
|
||||
assert values["MINDNET_ALLOW_CLOUD_EGRESS"] == "false"
|
||||
|
||||
|
||||
# --- Gitea-Workflows und Deploy-Skript (Muster wie Kansho: develop -> dev, main -> prod) ----
|
||||
|
||||
WORKFLOWS = {"deploy-dev.yml": ROOT / ".gitea" / "workflows", # aktiv
|
||||
"deploy-prod.yml": DEPLOY / "gitea-workflows"} # Vorlage bis zur Umschaltung
|
||||
|
||||
|
||||
def _workflow(name):
|
||||
data = yaml.safe_load((WORKFLOWS[name] / name).read_text(encoding="utf-8"))
|
||||
return data, data.get("on", data.get(True)) # PyYAML liest den Schlüssel 'on' als True
|
||||
|
||||
|
||||
@pytest.mark.parametrize("name, branch, envname", [("deploy-dev.yml", "develop", "dev"),
|
||||
("deploy-prod.yml", "main", "prod")])
|
||||
def test_workflow_maps_branch_to_environment(name, branch, envname):
|
||||
wf, on = _workflow(name)
|
||||
assert on["push"]["branches"] == [branch]
|
||||
job = wf["jobs"]["deploy"]
|
||||
assert job["runs-on"] == "linux_host"
|
||||
assert job["env"]["MINDNET_ENV_FILE"].startswith("/") and job["env"]["MINDNET_ENV_FILE"].endswith("container.env")
|
||||
assert job["env"]["MINDNET_APP_ENV_FILE"] == SYSTEMD_ENV_FILES[envname]
|
||||
assert any(s.get("run") == f"bash deploy/deploy.sh {envname}" for s in job["steps"])
|
||||
|
||||
|
||||
def test_prod_workflow_shares_concurrency_with_systemd_deploy():
|
||||
wf, _ = _workflow("deploy-prod.yml")
|
||||
systemd = yaml.safe_load((ROOT / ".gitea" / "workflows" / "deploy.yml").read_text(encoding="utf-8"))
|
||||
assert wf["concurrency"]["group"] == systemd["concurrency"]["group"]
|
||||
|
||||
|
||||
def test_deploy_script_checks_before_touching_running_stack():
|
||||
script = (DEPLOY / "deploy.sh").read_text(encoding="utf-8")
|
||||
assert "\r" not in script
|
||||
steps = script.split('step "1/5', 1)[1] # ohne Kopfkommentar und Funktionsdefinitionen
|
||||
order = [steps.index(s) for s in ("--network none", "preflight --live", "up -d --wait --no-build --remove-orphans && smoke")]
|
||||
assert order == sorted(order)
|
||||
assert "preflight --live" in script and "run --rm --no-deps api preflight" in script
|
||||
assert "--require-data" in script and "deploy/appenv.py" in script
|
||||
assert "last_good_tag" in script
|
||||
|
||||
|
||||
@pytest.mark.parametrize("envname", ["dev", "prod"])
|
||||
def test_compose_reads_systemd_env_then_container_env(envname):
|
||||
files = COMPOSE[envname]["x-hardening"]["env_file"]
|
||||
assert files[0].startswith("${MINDNET_APP_ENV_FILE:?")
|
||||
assert files[1] == f"${{MINDNET_ENV_FILE:-env/{envname}.env}}"
|
||||
|
||||
|
||||
def test_prod_workflow_not_active_before_switchover():
|
||||
assert not (ROOT / ".gitea" / "workflows" / "deploy-prod.yml").exists()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("name", ["deploy-dev.yml", "deploy-prod.yml"])
|
||||
def test_workflow_needs_no_external_actions(name):
|
||||
# Der Runner-Host soll ohne Internet/DNS deployen können (kein github.com).
|
||||
wf, _ = _workflow(name)
|
||||
assert not [s["uses"] for s in wf["jobs"]["deploy"]["steps"] if "uses" in s]
|
||||
Reference in new issue
Block a user