Programmmanagement/ARCHITECTURE_SNAPSHOT_v2.2.1.md

@@ -1,27 +0,0 @@
-# Architecture Snapshot v2.2.1
-**Stand:** Nach Abschluss von WP-04c
-**Kontext:** Wichtig für WP-05 Entwicklung.
-
-## 1. Neue Komponenten (Seit v2.2.0)
-
-### A. Feedback Service (`app/services/feedback_service.py`)
-- **Zweck:** Logging von Trainingsdaten für späteres Self-Tuning (WP-08).
-- **Storage:** Lokale JSONL-Dateien in `data/logs/` (Append-Only).
-  - `search_history.jsonl`: Query + Snapshot der Ergebnisse (Scores).
-  - `feedback.jsonl`: User-Rating zu spezifischer `node_id`.
-
-### B. Explanation Layer (`app/core/retriever.py`)
-- **Logik:** Der Retriever berechnet nicht nur Scores, sondern generiert `Explanation`-Objekte.
-- **Graph:** `Subgraph` (in `graph_adapter.py`) führt jetzt auch `reverse_adj` (Incoming Edges), um zu erklären, warum ein Knoten wichtig ist ("Referenziert von...").
-
-### C. DTOs (`app/models/dto.py`)
-Das Datenmodell wurde massiv erweitert. Wichtige Klassen für WP-05:
-- `QueryResponse`: Enthält jetzt `query_id` (UUID).
-- `QueryHit`: Enthält optional `explanation` (Typ `Explanation`).
-- `FeedbackRequest`: Für den Feedback-Loop.
-
-## 2. Implikationen für WP-05 (Chat)
-
-1.  **Logging:** Auch der neue `/chat` Endpoint sollte idealerweise die `query_id` loggen oder nutzen, um Konsistenz zu wahren.
-2.  **DTO-Nutzung:** Der Chat-Service wird intern den Retriever aufrufen. Er muss mit den `QueryHit`-Objekten arbeiten, um den Kontext für das LLM zu bauen.
-3.  **Config:** Die Persönlichkeit wird in `config/prompts.yaml` definiert (Late Binding), nicht im Python-Code hardcodiert.

app/main.py

@@ -1,43 +1,43 @@
 """
-app/main.py — mindnet API bootstrap
+app/main.py — mindnet API bootstrap (WP-04 Hooks)
+Version: 0.4.2 • Stand: 2025-10-07
 """
+
 from __future__ import annotations
 from fastapi import FastAPI
 from .config import get_settings
 from .routers.embed_router import router as embed_router
 from .routers.qdrant_router import router as qdrant_router
 
+# WP-04 Router:
 from .routers.query import router as query_router
 from .routers.graph import router as graph_router
 from .routers.tools import router as tools_router
-# NEU: Feedback Router
+# Optional:
-from .routers.feedback import router as feedback_router
-
 try:
     from .routers.admin import router as admin_router
 except Exception:
     admin_router = None
 
 def create_app() -> FastAPI:
-    app = FastAPI(title="mindnet API", version="0.4.3") # Version bump
+    app = FastAPI(title="mindnet API", version="0.1.0")
     s = get_settings()
 
     @app.get("/healthz")
     def healthz():
         return {"status": "ok", "qdrant": s.QDRANT_URL, "prefix": s.COLLECTION_PREFIX}
 
+    # Bestehende Router (unverändert)
     app.include_router(embed_router)
     app.include_router(qdrant_router)
 
+    # WP-04 Endpunkte
     app.include_router(query_router, prefix="/query", tags=["query"])
     app.include_router(graph_router, prefix="/graph", tags=["graph"])
     app.include_router(tools_router, prefix="/tools", tags=["tools"])
-    # NEU:
-    app.include_router(feedback_router, prefix="/feedback", tags=["feedback"])
-
     if admin_router:
         app.include_router(admin_router, prefix="/admin", tags=["admin"])
 
     return app
 
-app = create_app()
+app = create_app()

app/models/dto.py

@@ -4,26 +4,28 @@ app/models/dto.py — Pydantic-Modelle (DTOs) für WP-04 Endpunkte
 Zweck:
     Laufzeit-Modelle für FastAPI (Requests/Responses), getrennt von JSON-Schemas.
     Deckt die Graph-/Retriever-Endpunkte ab.
-    Enthält Erweiterungen für WP-04b (Explanation Layer) und WP-04c (Feedback).
+    Enthält Erweiterungen für WP-04b (Explanation Layer).
 
 Kompatibilität:
     Python 3.12+, Pydantic 2.x, FastAPI 0.110+
 Version:
-    0.3.0  (Update für WP-04c Feedback)
+    0.2.0  (Update für WP-04b Explanation Layer)
 Stand:
     2025-12-07
+Bezug:
+    - schemas/*.json (Speicherschema für Notes/Chunks/Edges)
+    - WP-04 API-Design (Query- und Graph-Endpunkte)
+Nutzung:
+    from app.models.dto import QueryRequest, QueryResponse, GraphResponse
 """
 
 from __future__ import annotations
 from pydantic import BaseModel, Field
 from typing import List, Literal, Optional, Dict, Any
-import uuid
 
 EdgeKind = Literal["references", "references_at", "backlink", "next", "prev", "belongs_to", "depends_on", "related_to", "similar_to"]
 
 
-# --- Basis-DTOs ---
-
 class NodeDTO(BaseModel):
     """Darstellung eines Knotens (Note oder Chunk) im API-Graph."""
     id: str
@@ -49,14 +51,12 @@ class EdgeDTO(BaseModel):
     direction: Literal["out", "in", "undirected"] = "out"
 
 
-# --- Request Models ---
-
 class QueryRequest(BaseModel):
     """
     Request für /query:
     - mode: 'semantic' | 'edge' | 'hybrid'
-    - query: (optional) Freitext
+    - query: (optional) Freitext; Embedding wird später angebunden
-    - query_vector: (optional) direkter Vektor
+    - query_vector: (optional) direkter Vektor (384d) für Quick-Tests ohne Embedding
     - explain: (optional) Fordert detaillierte Erklärungen an (WP-04b)
     """
     mode: Literal["semantic", "edge", "hybrid"] = "hybrid"
@@ -65,29 +65,24 @@ class QueryRequest(BaseModel):
     top_k: int = 10
     expand: Dict = {"depth": 1, "edge_types": ["references", "belongs_to", "prev", "next", "depends_on", "related_to"]}
     filters: Optional[Dict] = None
+    # Flags zur Steuerung der Rückgabe
     ret: Dict = {"with_paths": True, "with_notes": True, "with_chunks": True}
+    # WP-04b: Soll eine Erklärung generiert werden?
     explain: bool = False
 
 
-class FeedbackRequest(BaseModel):
-    """
-    User-Feedback zu einem spezifischen Treffer (WP-04c).
-    """
-    query_id: str = Field(..., description="ID der ursprünglichen Suche")
-    node_id: str = Field(..., description="ID des bewerteten Treffers")
-    score: int = Field(..., ge=0, le=1, description="1 (Positiv) oder 0 (Negativ/Irrelevant)")
-    comment: Optional[str] = None
-
-
 # --- WP-04b Explanation Models ---
 
 class ScoreBreakdown(BaseModel):
-    """Aufschlüsselung der Score-Komponenten."""
+    """
+    Aufschlüsselung der Score-Komponenten.
+    Zeigt die gewichteten Beiträge zum Total Score.
+    """
     semantic_contribution: float = Field(..., description="W_sem * semantic_score * weight")
     edge_contribution: float = Field(..., description="W_edge * edge_bonus")
     centrality_contribution: float = Field(..., description="W_cent * centrality_bonus")
     
-    # Rohwerte
+    # Rohwerte für Transparenz
     raw_semantic: float
     raw_edge_bonus: float
     raw_centrality: float
@@ -95,7 +90,10 @@ class ScoreBreakdown(BaseModel):
 
 
 class Reason(BaseModel):
-    """Ein semantischer Grund für das Ranking."""
+    """
+    Ein semantischer Grund für das Ranking.
+    z.B. 'Verlinkt von Projekt X', 'Hohe Textähnlichkeit'.
+    """
     kind: Literal["semantic", "edge", "type", "centrality"]
     message: str
     score_impact: Optional[float] = None
@@ -103,20 +101,24 @@ class Reason(BaseModel):
 
 
 class Explanation(BaseModel):
-    """Container für alle Erklärungsdaten eines Treffers."""
+    """
+    Container für alle Erklärungsdaten eines Treffers.
+    """
     breakdown: ScoreBreakdown
     reasons: List[Reason]
+    # Optional: Pfade im Graphen, die zu diesem Treffer geführt haben
     related_edges: Optional[List[EdgeDTO]] = None
 
 
-# --- Response Models ---
+# --- End Explanation Models ---
+
 
 class QueryHit(BaseModel):
     """Einzelnes Trefferobjekt für /query."""
     node_id: str
     note_id: Optional[str]
     
-    # Flache Scores
+    # Flache Scores (Kompatibilität WP-04a)
     semantic_score: float
     edge_bonus: float
     centrality_bonus: float
@@ -125,23 +127,19 @@ class QueryHit(BaseModel):
     paths: Optional[List[List[Dict]]] = None
     source: Optional[Dict] = None
     
-    # WP-04b: Erklärungsobjekt
+    # WP-04b: Erklärungsobjekt (nur gefüllt, wenn explain=True)
     explanation: Optional[Explanation] = None
 
 
 class QueryResponse(BaseModel):
-    """
+    """Antwortstruktur für /query (Liste von Treffern + Telemetrie)."""
-    Antwortstruktur für /query (Liste von Treffern + Telemetrie).
-    Enthält query_id für Traceability (WP-04c).
-    """
-    query_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
     results: List[QueryHit]
     used_mode: str
     latency_ms: int
 
 
 class GraphResponse(BaseModel):
-    """Antwortstruktur für /graph/{note_id}."""
+    """Antwortstruktur für /graph/{note_id} (Nachbarschaft)."""
     center_note_id: str
     nodes: List[NodeDTO]
     edges: List[EdgeDTO]

app/routers/feedback.py

@@ -1,20 +0,0 @@
-"""
-app/routers/feedback.py
-Endpunkt für User-Feedback (WP-04c).
-"""
-from fastapi import APIRouter, HTTPException
-from app.models.dto import FeedbackRequest
-from app.services.feedback_service import log_feedback
-
-router = APIRouter()
-
-@router.post("", status_code=201)
-def post_feedback(fb: FeedbackRequest):
-    """
-    Nimmt Feedback entgegen (z.B. Daumen hoch für einen Treffer).
-    """
-    try:
-        log_feedback(fb)
-        return {"status": "recorded", "query_id": fb.query_id}
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))

app/routers/query.py

@@ -15,31 +15,24 @@ Bezug:
 Nutzung:
     app.include_router(query.router, prefix="/query", tags=["query"])
 Änderungsverlauf:
-    0.2.0 (2025-12-07) - Update für WP04c Feedback
     0.1.0 (2025-10-07) – Erstanlage.
 """
+
 from __future__ import annotations
-from fastapi import APIRouter, HTTPException, BackgroundTasks
+from fastapi import APIRouter, HTTPException
 from app.models.dto import QueryRequest, QueryResponse
 from app.core.retriever import hybrid_retrieve, semantic_retrieve
-# NEU:
-from app.services.feedback_service import log_search
 
 router = APIRouter()
 
 @router.post("", response_model=QueryResponse)
-def post_query(req: QueryRequest, background_tasks: BackgroundTasks) -> QueryResponse:
+def post_query(req: QueryRequest) -> QueryResponse:
     try:
         if req.mode == "semantic":
-            res = semantic_retrieve(req)
+            return semantic_retrieve(req)
-        else:
+        # default: hybrid
-            res = hybrid_retrieve(req)
+        return hybrid_retrieve(req)
-        
-        # WP-04c: Logging im Hintergrund (bremst Antwort nicht)
-        background_tasks.add_task(log_search, req, res)
-        
-        return res
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
     except Exception as e:
-        raise HTTPException(status_code=500, detail=f"query failed: {e}")
+        raise HTTPException(status_code=500, detail=f"query failed: {e}")

app/services/feedback_service.py

@@ -1,80 +0,0 @@
-"""
-app/services/feedback_service.py
-Service zum Loggen von Suchanfragen und Feedback (WP-04c).
-Speichert Daten als JSONL für späteres Self-Tuning (WP-08).
-"""
-import json
-import os
-import time
-from pathlib import Path
-from typing import Dict, Any, List
-from app.models.dto import QueryRequest, QueryResponse, FeedbackRequest
-
-# Pfad für Logs (lokal auf dem Beelink/PC)
-LOG_DIR = Path("data/logs")
-SEARCH_LOG_FILE = LOG_DIR / "search_history.jsonl"
-FEEDBACK_LOG_FILE = LOG_DIR / "feedback.jsonl"
-
-def _ensure_log_dir():
-    if not LOG_DIR.exists():
-        os.makedirs(LOG_DIR, exist_ok=True)
-
-def log_search(req: QueryRequest, res: QueryResponse):
-    """
-    Speichert den "Snapshot" der Suche.
-    WICHTIG: Wir speichern die Scores (Breakdown), damit wir später wissen,
-    warum das System so entschieden hat.
-    """
-    _ensure_log_dir()
-    
-    # Wir reduzieren die Datenmenge etwas (z.B. keine vollen Texte)
-    hits_summary = []
-    for hit in res.results:
-        # Falls Explanation an war, speichern wir den Breakdown, sonst die Scores
-        breakdown = None
-        if hit.explanation and hit.explanation.breakdown:
-            breakdown = hit.explanation.breakdown.model_dump()
-            
-        hits_summary.append({
-            "node_id": hit.node_id,
-            "note_id": hit.note_id,
-            "total_score": hit.total_score,
-            "breakdown": breakdown, # Wichtig für Training!
-            "rank_semantic": hit.semantic_score,
-            "rank_edge": hit.edge_bonus
-        })
-
-    entry = {
-        "timestamp": time.time(),
-        "query_id": res.query_id,
-        "query_text": req.query,
-        "mode": req.mode,
-        "top_k": req.top_k,
-        "hits": hits_summary
-    }
-
-    try:
-        with open(SEARCH_LOG_FILE, "a", encoding="utf-8") as f:
-            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
-    except Exception as e:
-        print(f"ERROR logging search: {e}")
-
-def log_feedback(fb: FeedbackRequest):
-    """
-    Speichert das User-Feedback.
-    """
-    _ensure_log_dir()
-    
-    entry = {
-        "timestamp": time.time(),
-        "query_id": fb.query_id,
-        "node_id": fb.node_id,
-        "score": fb.score,
-        "comment": fb.comment
-    }
-
-    try:
-        with open(FEEDBACK_LOG_FILE, "a", encoding="utf-8") as f:
-            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
-    except Exception as e:
-        print(f"ERROR logging feedback: {e}")

docs/dev_workflow.md

@@ -1,6 +1,6 @@
 # Mindnet v2.2 – Entwickler-Workflow
 **Datei:** `DEV_WORKFLOW.md`
-**Stand:** 2025-12-07 (Aktualisiert: Sync-First Strategie)
+**Stand:** 2025-12-07 (Aktualisiert nach WP-04b)
 
 Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
 
@@ -22,14 +22,12 @@ Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE),
 
 Hier erstellst du die neue Funktion in einer sicheren Umgebung.
 
-1.  **Basis aktualisieren (WICHTIG!):**
+1.  **Sicherstellen, dass Git bereit ist:**
-    Bevor du startest, muss dein lokales `main` auf dem Stand des Servers sein.
+    * Öffne VS Code.
-    * Klicke unten links auf den aktuellen Branch und wähle **`main`**.
+    * Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. `main`).
-    * Klicke links im Menü "Source Control" auf die **drei Punkte (...)** -> **Pull** (oder das Synchronisieren-Symbol).
-    * *Erst jetzt hast du alle Dateien!*
 
-2.  **Branch erstellen:**
+2.  **Branch erstellen (WICHTIG):**
-    * Klicke wieder unten links auf `main`.
+    * Klicke unten links auf den Branch-Namen.
     * Wähle `+ Create new branch...`.
     * Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
     * Drücke **Enter**.
@@ -71,9 +69,9 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.
     ```
 
 5.  **Test-Server neustarten (WICHTIG):**
-    Falls noch ein alter Prozess läuft, musst du ihn beenden.
+    Falls noch ein alter Prozess läuft, musst du ihn beenden, damit der neue Code geladen wird.
     * Drücke `Strg + C` falls der Server noch im Vordergrund läuft.
-    * Oder nutze `pkill -f "uvicorn app.main:app"`.
+    * Oder nutze `pkill -f "uvicorn app.main:app"` um Hintergrunde-Prozesse zu stoppen.
 
     Starten auf **Port 8002**:
     ```bash
@@ -129,7 +127,6 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
     ```
 3.  **VS Code:**
     * Auf `main` wechseln.
-    * Sync drücken (um Löschung vom Server zu erfahren).
     * `F1` -> `Git: Delete Branch` -> Branch auswählen.
 
 ---
@@ -138,23 +135,23 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
 
 | Wo? | Befehl | Was tut es? |
 | :--- | :--- | :--- |
-| **VS Code** | `Sync (auf main)` | **WICHTIG:** Holt neuesten Code vom Server. |
+| **VS Code** | `Klick auf Branch-Namen` | Branch erstellen oder wechseln. |
-| **VS Code** | `Klick auf Branch` | Branch erstellen oder wechseln. |
+| **VS Code** | `Sync Changes` | Lädt Code zu Gitea hoch. |
+| **Beelink** | `cd ~/mindnet_dev` | Gehe in den Test-Ordner. |
 | **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
-| **Beelink** | `git fetch` | Aktualisiert Remote-Branches. |
+| **Beelink** | `git fetch` | Aktualisiert die Liste der Remote-Branches. |
-| **Beelink** | `git checkout <name>` | Wechsle Branch. |
+| **Beelink** | `git branch -r` | Zeigt alle Branches auf dem Server an. |
-| **Beelink** | `git pull` | Aktualisiere aktuellen Branch. |
+| **Beelink** | `git checkout <name>` | Wechsle auf einen anderen Branch. |
 | **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |
 
 ---
 
-## 4. Troubleshooting
+## 4. Sicherheitsregeln
 
-**"Hilfe, in meinem neuen Branch fehlen Dateien!"**
+1.  **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren. Dieser Ordner bleibt immer auf `main`.
-Das passiert, wenn du beim Erstellen nicht aktuell warst.
+2.  **Niemals** beide Umgebungen auf denselben `COLLECTION_PREFIX` zeigen lassen.
-* **Lösung:**
+    * Prod `.env`: `COLLECTION_PREFIX="mindnet"`
-  ```bash
+    * Dev `.env`: `COLLECTION_PREFIX="mindnet_dev"`
-  # In VS Code Terminal:
+3.  **Port-Disziplin:**
-  git checkout feature/mein-kaputter-branch
+    * **PROD:** Port 8001
-  git merge main
+    * **DEV:** Port 8002
-  # (Das holt die fehlenden Dateien aus main nach)

tests/test_feedback_smoke.py

@@ -1,65 +0,0 @@
-import requests
-import json
-import sys
-import time
-
-# Konfiguration
-BASE_URL = "http://localhost:8002"
-QUERY_URL = f"{BASE_URL}/query"
-FEEDBACK_URL = f"{BASE_URL}/feedback"
-
-def run_test():
-    print(f"--- 1. Sende Suchanfrage an {QUERY_URL} ---")
-    query_payload = {
-        "query": "mindnet architecture",
-        "mode": "hybrid",
-        "top_k": 2,
-        "explain": True # Wir wollen auch Breakdown loggen
-    }
-    
-    try:
-        r = requests.post(QUERY_URL, json=query_payload)
-        r.raise_for_status()
-        res_data = r.json()
-    except Exception as e:
-        print(f"ERROR bei Suche: {e}")
-        sys.exit(1)
-
-    query_id = res_data.get("query_id")
-    results = res_data.get("results", [])
-    
-    if not query_id:
-        print("FAIL: Keine query_id in der Antwort erhalten!")
-        sys.exit(1)
-        
-    if not results:
-        print("WARNUNG: Keine Treffer gefunden, Test kann Feedback nur simuliert senden.")
-        target_node_id = "fake-node-id"
-    else:
-        target_node_id = results[0].get("node_id")
-
-    print(f"SUCCESS: Suche OK. Erhaltene Query-ID: {query_id}")
-    print(f"Target Node für Feedback: {target_node_id}")
-
-    # Kurze Pause, damit Background-Task Zeit hat zu schreiben (nur für Log-Check relevant)
-    time.sleep(0.5)
-
-    print(f"\n--- 2. Sende Feedback an {FEEDBACK_URL} ---")
-    feedback_payload = {
-        "query_id": query_id,
-        "node_id": target_node_id,
-        "score": 1,
-        "comment": "Automatisierter Smoke-Test: Dieser Treffer war hilfreich."
-    }
-
-    try:
-        r_fb = requests.post(FEEDBACK_URL, json=feedback_payload)
-        r_fb.raise_for_status()
-        print(f"SUCCESS: Feedback gesendet. Status: {r_fb.status_code}")
-        print(f"Response: {r_fb.json()}")
-    except Exception as e:
-        print(f"ERROR bei Feedback: {e}")
-        sys.exit(1)
-
-if __name__ == "__main__":
-    run_test()