Compare commits
11
Commits
5b9399361d
...
WP04_full
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
fbaa07ba88 | ||
|
|
d0ecc5316f | ||
|
|
9ee39277ae | ||
|
|
9d3fd21c88 | ||
|
|
d7217672a3 | ||
|
|
e39b685b1e | ||
|
|
7631b93900 | ||
|
|
f98eb8fc16 | ||
|
|
ab60106fb9 | ||
|
|
caab41a760 | ||
|
|
78d8ab11ed |
No files matched your search
@@ -0,0 +1,27 @@
|
||||
# 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.
|
||||
+9
-9
@@ -1,43 +1,43 @@
|
||||
"""
|
||||
app/main.py — mindnet API bootstrap (WP-04 Hooks)
|
||||
Version: 0.4.2 • Stand: 2025-10-07
|
||||
app/main.py — mindnet API bootstrap
|
||||
"""
|
||||
|
||||
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
|
||||
# Optional:
|
||||
# NEU: Feedback Router
|
||||
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.1.0")
|
||||
app = FastAPI(title="mindnet API", version="0.4.3") # Version bump
|
||||
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()
|
||||
+32
-30
@@ -4,28 +4,26 @@ 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).
|
||||
Enthält Erweiterungen für WP-04b (Explanation Layer) und WP-04c (Feedback).
|
||||
|
||||
Kompatibilität:
|
||||
Python 3.12+, Pydantic 2.x, FastAPI 0.110+
|
||||
Version:
|
||||
0.2.0 (Update für WP-04b Explanation Layer)
|
||||
0.3.0 (Update für WP-04c Feedback)
|
||||
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
|
||||
@@ -51,12 +49,14 @@ 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; Embedding wird später angebunden
|
||||
- query_vector: (optional) direkter Vektor (384d) für Quick-Tests ohne Embedding
|
||||
- query: (optional) Freitext
|
||||
- query_vector: (optional) direkter Vektor
|
||||
- explain: (optional) Fordert detaillierte Erklärungen an (WP-04b)
|
||||
"""
|
||||
mode: Literal["semantic", "edge", "hybrid"] = "hybrid"
|
||||
@@ -65,24 +65,29 @@ 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.
|
||||
Zeigt die gewichteten Beiträge zum Total Score.
|
||||
"""
|
||||
"""Aufschlüsselung der Score-Komponenten."""
|
||||
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 für Transparenz
|
||||
# Rohwerte
|
||||
raw_semantic: float
|
||||
raw_edge_bonus: float
|
||||
raw_centrality: float
|
||||
@@ -90,10 +95,7 @@ class ScoreBreakdown(BaseModel):
|
||||
|
||||
|
||||
class Reason(BaseModel):
|
||||
"""
|
||||
Ein semantischer Grund für das Ranking.
|
||||
z.B. 'Verlinkt von Projekt X', 'Hohe Textähnlichkeit'.
|
||||
"""
|
||||
"""Ein semantischer Grund für das Ranking."""
|
||||
kind: Literal["semantic", "edge", "type", "centrality"]
|
||||
message: str
|
||||
score_impact: Optional[float] = None
|
||||
@@ -101,24 +103,20 @@ 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
|
||||
|
||||
|
||||
# --- End Explanation Models ---
|
||||
|
||||
# --- Response Models ---
|
||||
|
||||
class QueryHit(BaseModel):
|
||||
"""Einzelnes Trefferobjekt für /query."""
|
||||
node_id: str
|
||||
note_id: Optional[str]
|
||||
|
||||
# Flache Scores (Kompatibilität WP-04a)
|
||||
# Flache Scores
|
||||
semantic_score: float
|
||||
edge_bonus: float
|
||||
centrality_bonus: float
|
||||
@@ -127,19 +125,23 @@ class QueryHit(BaseModel):
|
||||
paths: Optional[List[List[Dict]]] = None
|
||||
source: Optional[Dict] = None
|
||||
|
||||
# WP-04b: Erklärungsobjekt (nur gefüllt, wenn explain=True)
|
||||
# WP-04b: Erklärungsobjekt
|
||||
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} (Nachbarschaft)."""
|
||||
"""Antwortstruktur für /graph/{note_id}."""
|
||||
center_note_id: str
|
||||
nodes: List[NodeDTO]
|
||||
edges: List[EdgeDTO]
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
"""
|
||||
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))
|
||||
+14
-7
@@ -15,24 +15,31 @@ 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
|
||||
from fastapi import APIRouter, HTTPException, BackgroundTasks
|
||||
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) -> QueryResponse:
|
||||
def post_query(req: QueryRequest, background_tasks: BackgroundTasks) -> QueryResponse:
|
||||
try:
|
||||
if req.mode == "semantic":
|
||||
return semantic_retrieve(req)
|
||||
# default: hybrid
|
||||
return hybrid_retrieve(req)
|
||||
res = semantic_retrieve(req)
|
||||
else:
|
||||
res = 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}")
|
||||
@@ -0,0 +1,80 @@
|
||||
"""
|
||||
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}")
|
||||
+62
-82
@@ -1,7 +1,7 @@
|
||||
# Mindnet v2.2 – Admin Guide
|
||||
**Datei:** `docs/mindnet_admin_guide_v2.2.md`
|
||||
**Stand:** 2025-12-07
|
||||
**Status:** **FINAL** (Konsolidiert WP02–WP04a)
|
||||
**Stand:** 2025-12-08
|
||||
**Status:** **FINAL** (Konsolidiert WP02–WP04c)
|
||||
**Quellen:** `Handbuch.md`, `mindnet_v2_implementation_playbook.md`, `mindnet_technical_architecture.md`, `Programmplan_V2.2.md`.
|
||||
|
||||
> Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz.
|
||||
@@ -11,15 +11,13 @@
|
||||
## 1. Zielgruppe & Scope
|
||||
|
||||
Mindnet ist als **Single-Node System** konzipiert, das lokal (z.B. Laptop) oder auf einem privaten Server (Homelab, Intranet) läuft.
|
||||
Als Admin bist du verantwortlich für:
|
||||
* Die Verfügbarkeit der Dienste (Qdrant, API).
|
||||
* Die Datensicherheit (Backups).
|
||||
* Die Integrität des Imports (Sync zwischen Vault und DB).
|
||||
* Die Governance (wer darf zugreifen).
|
||||
Wir unterscheiden strikt zwischen:
|
||||
* **Production (Port 8001):** Stabiler `main` Branch.
|
||||
* **Development (Port 8002):** Experimentelle Feature-Branches.
|
||||
|
||||
---
|
||||
|
||||
## 2. Initial Setup
|
||||
## 2. Initial Setup & Installation
|
||||
|
||||
### 2.1 Systemvoraussetzungen
|
||||
* **OS:** Linux (Ubuntu 22.04+ empfohlen) oder macOS.
|
||||
@@ -29,10 +27,10 @@ Als Admin bist du verantwortlich für:
|
||||
* RAM: Min. 4GB (abhängig von der Vault-Größe und Qdrant-Index).
|
||||
* Disk: SSD empfohlen für Qdrant-Performance.
|
||||
|
||||
### 2.2 Installation
|
||||
### 2.2 Installation (Code)
|
||||
# 1. Repository klonen
|
||||
git clone <repo-url> /opt/mindnet
|
||||
cd /opt/mindnet
|
||||
git clone <repo-url> /home/llmadmin/mindnet
|
||||
cd /home/llmadmin/mindnet
|
||||
|
||||
# 2. Umgebung einrichten
|
||||
python3 -m venv .venv
|
||||
@@ -40,7 +38,7 @@ Als Admin bist du verantwortlich für:
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 3. Verzeichnisse anlegen
|
||||
mkdir -p logs qdrant_storage
|
||||
mkdir -p logs qdrant_storage data/logs
|
||||
|
||||
### 2.3 Qdrant Setup (Docker)
|
||||
Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig.
|
||||
@@ -59,132 +57,114 @@ Erstelle eine `.env` Datei im Root-Verzeichnis. Diese Variablen steuern das Verh
|
||||
QDRANT_API_KEY="" # Leer lassen für lokale Instanzen ohne Auth
|
||||
|
||||
# Mindnet Core Settings
|
||||
COLLECTION_PREFIX="mindnet"
|
||||
COLLECTION_PREFIX="mindnet" # "mindnet_dev" für Dev-Umgebung
|
||||
MINDNET_TYPES_FILE="./config/types.yaml"
|
||||
MINDNET_RETRIEVER_CONFIG="./config/retriever.yaml"
|
||||
|
||||
# Embedding Settings (Default: all-MiniLM-L6-v2)
|
||||
VECTOR_DIM=384
|
||||
|
||||
# Import-Strategie (Performance vs. Gründlichkeit)
|
||||
# Body: Nur Textänderungen triggern Update (Standard)
|
||||
# Full: Auch Frontmatter-Änderungen (z.B. Tags) triggern Update
|
||||
# Import-Strategie
|
||||
MINDNET_HASH_COMPARE="Body"
|
||||
MINDNET_HASH_SOURCE="parsed"
|
||||
|
||||
### 2.5 Deployment via Systemd (Standard ab v2.2.1)
|
||||
Mindnet wird nicht mehr manuell gestartet, sondern als Systemdienst.
|
||||
|
||||
**Production Service (`/etc/systemd/system/mindnet-prod.service`):**
|
||||
* Läuft auf Port 8001.
|
||||
* Autostart (`enabled`).
|
||||
* Restart Policy: `always` (heilt Abstürze automatisch).
|
||||
|
||||
**Development Service (`/etc/systemd/system/mindnet-dev.service`):**
|
||||
* Läuft auf Port 8002.
|
||||
* Getrennter Ordner (`~/mindnet_dev`).
|
||||
|
||||
---
|
||||
|
||||
## 3. Betrieb im Alltag
|
||||
|
||||
### 3.1 Regelmäßige Importe
|
||||
Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob oder Trigger) nach Qdrant synchronisiert werden. Das Skript erkennt Änderungen automatisch.
|
||||
Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant synchronisiert werden.
|
||||
|
||||
**Cronjob-Beispiel (stündlich):**
|
||||
0 * * * * cd /opt/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1
|
||||
0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1
|
||||
|
||||
* `--purge-before-upsert`: Wichtig, um Fragmente gelöschter Textstellen zu entfernen.
|
||||
* `--sync-deletes`: Wichtig, um Notizen aus dem Index zu entfernen, die im Vault gelöscht wurden.
|
||||
* `--purge-before-upsert`: Entfernt Fragmente gelöschter Textstellen.
|
||||
* `--sync-deletes`: Entfernt Notizen aus dem Index, die im Vault gelöscht wurden.
|
||||
|
||||
### 3.2 Health-Checks
|
||||
Prüfe regelmäßig, ob die API und der Retriever korrekt arbeiten.
|
||||
|
||||
**API Status Check:**
|
||||
curl -f http://localhost:8000/health || echo "API Down"
|
||||
**System Status:**
|
||||
sudo systemctl status mindnet-prod
|
||||
|
||||
**Logischer Smoke-Test:**
|
||||
Führt eine echte Hybrid-Suche durch und prüft, ob Scores berechnet werden.
|
||||
python3 scripts/test_retriever_smoke.py --mode hybrid
|
||||
python3 scripts/test_retriever_smoke.py --mode hybrid --url http://localhost:8001/query
|
||||
|
||||
### 3.3 Umgang mit Fehlern im Importer
|
||||
Falls der Importer abbricht oder Dateien ignoriert:
|
||||
### 3.3 Logs & Monitoring
|
||||
Seit v2.2.1 werden technische Logs im Systemd Journal und fachliche Logs in JSONL-Dateien gespeichert.
|
||||
|
||||
1. **Diagnose:** Nutze `scripts/diagnose_changed.py`, um zu sehen, warum eine Datei als "unchanged" gilt.
|
||||
python3 -m scripts.diagnose_changed --vault ./vault --note-id "MeineProblemnote"
|
||||
2. **Schema-Validierung:** Prüfe mit `scripts/payload_dryrun.py`, ob eine spezifische Datei das JSON-Schema verletzt.
|
||||
3. **Erzwingen:** Nutze `touch <filename>` im Vault, um den Zeitstempel zu aktualisieren und Hash-Checks zu umgehen, oder nutze `--force` (Vorsicht: Performance).
|
||||
* **Technische Fehler (Live):**
|
||||
`journalctl -u mindnet-prod -f`
|
||||
* **Fachliche Logs (Data Flywheel):**
|
||||
`/home/llmadmin/mindnet/data/logs/search_history.jsonl`
|
||||
`/home/llmadmin/mindnet/data/logs/feedback.jsonl`
|
||||
|
||||
> **Hinweis:** Die JSONL-Logs wachsen endlos ("Append Only"). Richte bei Bedarf `logrotate` ein oder archiviere alte Logs. Lösche sie nicht, da sie die Basis für WP08 (Self-Tuning) sind.
|
||||
|
||||
---
|
||||
|
||||
## 4. Update-Prozess
|
||||
|
||||
Wenn neue Versionen der Mindnet-Software (z.B. Schema-Updates in WP05) ausgerollt werden:
|
||||
Wenn neue Versionen ausgerollt werden (Deployment):
|
||||
|
||||
1. **Code aktualisieren:**
|
||||
cd /home/llmadmin/mindnet
|
||||
git pull origin main
|
||||
2. **Dependencies prüfen:**
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
3. **Schema-Migration:**
|
||||
Mindnet nutzt oft "Rebuild" statt komplexer Migrationen, da der Vault die Source of Truth ist.
|
||||
* Prüfe `CHANGELOG.md` auf "Breaking Changes".
|
||||
* Bei Schema-Änderungen: Führe einen **Full Rebuild** durch (siehe 5.3).
|
||||
3. **Dienst neustarten (Zwingend!):**
|
||||
sudo systemctl restart mindnet-prod
|
||||
4. **Schema-Migration (falls nötig):**
|
||||
Bei Änderungen an `types.yaml` oder Index-Strukturen:
|
||||
python3 -m scripts.import_markdown ... --apply
|
||||
|
||||
---
|
||||
|
||||
## 5. Backup & Restore
|
||||
|
||||
Datensicherheit ruht auf zwei Säulen: Dem Vault (Original) und Qdrant (Index).
|
||||
Datensicherheit ruht auf drei Säulen: Vault (Source), Qdrant (Index), JSONL-Logs (Lern-Daten).
|
||||
|
||||
### 5.1 Vault-Backup (Priorität 1)
|
||||
Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden.
|
||||
* **Strategie:** Git-Repository, rsync auf NAS, oder Cloud-Sync.
|
||||
* **Restore:** Einfach Dateien zurückkopieren und Import laufen lassen.
|
||||
Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden (Git/NAS).
|
||||
|
||||
### 5.2 Qdrant-Snapshots (Priorität 2)
|
||||
Für schnelle Wiederherstellung des Suchindex ohne stundenlangen Re-Import (bei großen Vaults).
|
||||
|
||||
**Backup erstellen (Volume-Level):**
|
||||
Für schnelle Wiederherstellung des Suchindex.
|
||||
docker stop mindnet_qdrant
|
||||
tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage
|
||||
docker start mindnet_qdrant
|
||||
|
||||
**Alternativ: API-Snapshot (Zero-Downtime):**
|
||||
Siehe Qdrant Dokumentation (Snapshot API).
|
||||
|
||||
**Restore:**
|
||||
1. Container stoppen.
|
||||
2. Inhalt von `qdrant_storage` löschen.
|
||||
3. Backup entpacken.
|
||||
4. Container starten.
|
||||
|
||||
### 5.3 Notfall-Wiederherstellung (Rebuild)
|
||||
Wenn die Datenbank korrupt ist oder Indizes defekt sind, ist der sauberste Weg ein Rebuild:
|
||||
### 5.3 Log-Daten (Priorität 3)
|
||||
Sichere den Ordner `data/logs/`. Verlust dieser Daten bedeutet, dass das System vergisst, welche Antworten Nutzer hilfreich fanden.
|
||||
|
||||
### 5.4 Notfall-Wiederherstellung (Rebuild)
|
||||
Wenn die Datenbank korrupt ist:
|
||||
# 1. DB komplett leeren (Wipe)
|
||||
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
|
||||
|
||||
# 2. Alles neu importieren
|
||||
python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply
|
||||
|
||||
---
|
||||
|
||||
## 6. Monitoring & Logging
|
||||
## 6. Governance & Sicherheit
|
||||
|
||||
### 6.1 Log-Quellen
|
||||
* **Importer:** Schreibt nach STDOUT/STDERR. Sollte im Cronjob in eine Datei (z.B. `/var/log/mindnet_import.log`) umgeleitet werden.
|
||||
* **API (Uvicorn):** Standard Access-Logs.
|
||||
* **Qdrant:** Docker Logs (`docker logs mindnet_qdrant`).
|
||||
### 6.1 Zugriffsschutz
|
||||
Mindnet hat aktuell **keine integrierte Authentifizierung**.
|
||||
* **API:** Muss hinter einem Reverse Proxy (Nginx, Traefik) mit Basic Auth laufen, wenn sie im Netzwerk freigegeben wird.
|
||||
* **Qdrant:** Sollte via Firewall (ufw) auf `127.0.0.1` beschränkt sein.
|
||||
|
||||
### 6.2 Wichtige Metriken (Log-Parsing)
|
||||
Achte in den Import-Logs auf folgende Muster:
|
||||
* `edges_created`: Sollte bei neuen Inhalten > 0 sein.
|
||||
* `chunks_created`: Sollte plausibel zur Anzahl neuer/geänderter Notizen sein.
|
||||
* `unresolved_references`: Ein hoher Anstieg deutet auf tote Links oder Tippfehler im Vault hin.
|
||||
* `ERROR` / `WARNING`: Parsing-Fehler (z.B. ungültiges YAML).
|
||||
|
||||
---
|
||||
|
||||
## 7. Governance & Sicherheit
|
||||
|
||||
### 7.1 Zugriffsschutz
|
||||
Mindnet hat aktuell **keine integrierte Authentifizierung** (By Design für lokalen Betrieb).
|
||||
* **API:** Muss hinter einem Reverse Proxy (Nginx, Traefik, Caddy) mit Basic Auth oder OAuth laufen, wenn sie im Netzwerk freigegeben wird.
|
||||
* **Qdrant:** Sollte nicht öffentlich erreichbar sein (Firewall auf Port 6333, `127.0.0.1` Bindung).
|
||||
|
||||
### 7.2 Datenschutz & Sichtbarkeit
|
||||
* **Interne Nutzung:** Standardmäßig sind alle Inhalte im Index "internal".
|
||||
* **Trennung:** Wenn du öffentliche und private Daten hast, nutze unterschiedliche `COLLECTION_PREFIX` (z.B. `mindnet_public`, `mindnet_private`) und getrennte Import-Jobs/Vault-Ordner, oder warte auf die WP05-ACL-Implementierung (Filterung auf API-Ebene).
|
||||
|
||||
### 7.3 Typen-Governance
|
||||
### 6.2 Typen-Governance
|
||||
Änderungen an der `types.yaml` (z.B. neue Gewichte) wirken global.
|
||||
* **Prozess:** Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen.
|
||||
* **Review:** Prüfe, ob neue Typen (`type: xyz`) auch Chunking-Profile haben, sonst fallen sie auf Defaults zurück.
|
||||
* **Prozess:** Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen.
|
||||
+19
-23
@@ -1,7 +1,7 @@
|
||||
# Mindnet v2.2 – Appendices & Referenzen
|
||||
**Datei:** `docs/mindnet_appendices_v2.2.md`
|
||||
**Stand:** 2025-12-07
|
||||
**Status:** **FINAL** (Konsolidiert aus WP01–WP04a)
|
||||
**Stand:** 2025-12-08
|
||||
**Status:** **FINAL**
|
||||
**Quellen:** `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_technical_architecture.md`, `Handbuch.md`.
|
||||
|
||||
> Dieses Dokument bündelt Tabellen, Schemata und technische Referenzen, die in den Prozess-Dokumenten (Playbook, Guides) den Lesefluss stören würden.
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
## Anhang A: Typ-Registry Referenz (Default-Werte)
|
||||
|
||||
Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.2). Diese Werte werden beim Import angewendet, sofern im Frontmatter nichts anderes definiert ist.
|
||||
Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.2).
|
||||
|
||||
| Typ (`type`) | Chunk Profile | Retriever Weight | Edge Defaults (Auto-Kanten) | Beschreibung |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
@@ -28,7 +28,7 @@ Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.2). Di
|
||||
|
||||
## Anhang B: Edge-Typen & Semantik
|
||||
|
||||
Referenz aller implementierten Kantenarten (`kind`). Die Spalte "Herkunft" zeigt, durch welchen Mechanismus diese Kante primär entsteht.
|
||||
Referenz aller implementierten Kantenarten (`kind`).
|
||||
|
||||
| Kind | Herkunft (Primär) | Symmetrisch? | Bedeutung & Nutzung |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
@@ -46,7 +46,7 @@ Referenz aller implementierten Kantenarten (`kind`). Die Spalte "Herkunft" zeigt
|
||||
|
||||
## Anhang C: Datenmodelle (JSON Payloads)
|
||||
|
||||
Dies sind die Felder, die effektiv in Qdrant gespeichert werden. Dient als Referenz für Entwickler und Debugging (`payload_dryrun`).
|
||||
Dies sind die Felder, die effektiv in Qdrant gespeichert werden.
|
||||
|
||||
### C.1 Note Payload (`mindnet_notes`)
|
||||
{
|
||||
@@ -101,31 +101,27 @@ Diese Variablen steuern das Verhalten der Skripte und Container.
|
||||
| `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. |
|
||||
| `MINDNET_HASH_COMPARE` | `Body` | Vergleichsmodus für Import (`Body`, `Frontmatter`, `Full`). |
|
||||
| `MINDNET_HASH_SOURCE` | `parsed` | Quelle für Hash (`parsed`, `raw`, `file`). |
|
||||
| `MINDNET_HASH_NORMALIZE` | `canonical` | Normalisierung vor Hash (`canonical`, `none`). |
|
||||
| `VECTOR_DIM` | `384` | Dimension der Embeddings (Modellabhängig). |
|
||||
|
||||
---
|
||||
|
||||
## Anhang E: Glossar
|
||||
|
||||
Zentrale Begriffe des Mindnet-Systems.
|
||||
|
||||
* **Callout-Edge:** Eine Kante, die durch einen Obsidian-Callout Block (`> [!edge]`) definiert wird. Dient für Listen.
|
||||
* **Chunking:** Prozess des Zerlegens einer Notiz in kleinere, semantische Einheiten (Chunks).
|
||||
* **Confidence:** Ein Wert (0.0-1.0), der angibt, wie sicher eine Kante ist. Explizite User-Eingaben haben 1.0, Defaults ~0.7.
|
||||
* **Idempotenz:** Eigenschaft des Importers, bei mehrfacher Ausführung das exakt gleiche Ergebnis zu liefern (keine Duplikate).
|
||||
* **Inline-Edge:** Eine Kante, die im Fließtext mittels `[[rel:type Ziel]]` definiert wird. Semantisch sehr stark.
|
||||
* **Provenance:** Die Herkunft einer Information (z.B. "explicit" vs "rule" vs "inference").
|
||||
* **Retriever:** Die Komponente (FastAPI), die Suchanfragen beantwortet und Scores berechnet.
|
||||
* **Rule ID:** Ein String, der genau identifiziert, welche Code-Regel eine Kante erzeugt hat (z.B. `edge_defaults:project:depends_on`).
|
||||
* **Vault:** Der lokale Ordner mit Markdown-Dateien. Die "Single Source of Truth".
|
||||
* **Vector Search:** Suche basierend auf semantischer Ähnlichkeit (Embeddings) statt reiner Stichworte.
|
||||
* **Callout-Edge:** Kante via `> [!edge]`.
|
||||
* **Chunking:** Zerlegung von Notizen in kleinere Einheiten.
|
||||
* **Confidence:** Vertrauenswürdigkeit einer Kante (0.0-1.0).
|
||||
* **Explanation Layer:** Komponente, die Scores und Graphen als Begründung liefert.
|
||||
* **Feedback Loop:** Prozess des Loggens und Auswertens von User-Reaktionen.
|
||||
* **Idempotenz:** Mehrfache Ausführung liefert gleiches Ergebnis.
|
||||
* **Inline-Edge:** Kante via `[[rel:type Ziel]]`.
|
||||
* **Retriever:** Suchmaschine (FastAPI).
|
||||
* **Vault:** Ordner mit Markdown-Dateien.
|
||||
|
||||
---
|
||||
|
||||
## Anhang F: Workpackage Status (v2.2)
|
||||
## Anhang F: Workpackage Status (v2.2.1)
|
||||
|
||||
Status der Module gemäß Programmplan.
|
||||
Aktueller Implementierungsstand der Module.
|
||||
|
||||
| WP | Titel | Status | Anmerkung |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
@@ -133,8 +129,8 @@ Status der Module gemäß Programmplan.
|
||||
| **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. |
|
||||
| **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. |
|
||||
| **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). |
|
||||
| **WP04b**| Explanation Layer | 🟡 In Arbeit | API liefert Pfade, UI fehlt noch. |
|
||||
| **WP04c**| Feedback Loop | 🔴 Geplant | Logging von User-Feedback. |
|
||||
| **WP05** | Virtual Schema | 🟡 Teilw. | `types.yaml` aktiv, ACL fehlt. |
|
||||
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
|
||||
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
|
||||
| **WP05** | Persönlichkeit / Chat | 🟡 Geplant | Nächster Schritt (RAG). |
|
||||
| **WP06** | Self-Healing | 🔴 Geplant | Auto-Fixing von Broken Links. |
|
||||
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
|
||||
+25
-22
@@ -1,6 +1,6 @@
|
||||
# Mindnet v2.2 – Entwickler-Workflow
|
||||
**Datei:** `DEV_WORKFLOW.md`
|
||||
**Stand:** 2025-12-07 (Aktualisiert nach WP-04b)
|
||||
**Stand:** 2025-12-07 (Aktualisiert: Sync-First Strategie)
|
||||
|
||||
Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
|
||||
|
||||
@@ -22,12 +22,14 @@ Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE),
|
||||
|
||||
Hier erstellst du die neue Funktion in einer sicheren Umgebung.
|
||||
|
||||
1. **Sicherstellen, dass Git bereit ist:**
|
||||
* Öffne VS Code.
|
||||
* Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. `main`).
|
||||
1. **Basis aktualisieren (WICHTIG!):**
|
||||
Bevor du startest, muss dein lokales `main` auf dem Stand des Servers sein.
|
||||
* Klicke unten links auf den aktuellen Branch und wähle **`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 (WICHTIG):**
|
||||
* Klicke unten links auf den Branch-Namen.
|
||||
2. **Branch erstellen:**
|
||||
* Klicke wieder unten links auf `main`.
|
||||
* Wähle `+ Create new branch...`.
|
||||
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
|
||||
* Drücke **Enter**.
|
||||
@@ -69,9 +71,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, damit der neue Code geladen wird.
|
||||
Falls noch ein alter Prozess läuft, musst du ihn beenden.
|
||||
* Drücke `Strg + C` falls der Server noch im Vordergrund läuft.
|
||||
* Oder nutze `pkill -f "uvicorn app.main:app"` um Hintergrunde-Prozesse zu stoppen.
|
||||
* Oder nutze `pkill -f "uvicorn app.main:app"`.
|
||||
|
||||
Starten auf **Port 8002**:
|
||||
```bash
|
||||
@@ -127,6 +129,7 @@ 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.
|
||||
|
||||
---
|
||||
@@ -135,23 +138,23 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
|
||||
|
||||
| Wo? | Befehl | Was tut es? |
|
||||
| :--- | :--- | :--- |
|
||||
| **VS Code** | `Klick auf Branch-Namen` | Branch erstellen oder wechseln. |
|
||||
| **VS Code** | `Sync Changes` | Lädt Code zu Gitea hoch. |
|
||||
| **Beelink** | `cd ~/mindnet_dev` | Gehe in den Test-Ordner. |
|
||||
| **VS Code** | `Sync (auf main)` | **WICHTIG:** Holt neuesten Code vom Server. |
|
||||
| **VS Code** | `Klick auf Branch` | Branch erstellen oder wechseln. |
|
||||
| **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
|
||||
| **Beelink** | `git fetch` | Aktualisiert die Liste der Remote-Branches. |
|
||||
| **Beelink** | `git branch -r` | Zeigt alle Branches auf dem Server an. |
|
||||
| **Beelink** | `git checkout <name>` | Wechsle auf einen anderen Branch. |
|
||||
| **Beelink** | `git fetch` | Aktualisiert Remote-Branches. |
|
||||
| **Beelink** | `git checkout <name>` | Wechsle Branch. |
|
||||
| **Beelink** | `git pull` | Aktualisiere aktuellen Branch. |
|
||||
| **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |
|
||||
|
||||
---
|
||||
|
||||
## 4. Sicherheitsregeln
|
||||
## 4. Troubleshooting
|
||||
|
||||
1. **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren. Dieser Ordner bleibt immer auf `main`.
|
||||
2. **Niemals** beide Umgebungen auf denselben `COLLECTION_PREFIX` zeigen lassen.
|
||||
* Prod `.env`: `COLLECTION_PREFIX="mindnet"`
|
||||
* Dev `.env`: `COLLECTION_PREFIX="mindnet_dev"`
|
||||
3. **Port-Disziplin:**
|
||||
* **PROD:** Port 8001
|
||||
* **DEV:** Port 8002
|
||||
**"Hilfe, in meinem neuen Branch fehlen Dateien!"**
|
||||
Das passiert, wenn du beim Erstellen nicht aktuell warst.
|
||||
* **Lösung:**
|
||||
```bash
|
||||
# In VS Code Terminal:
|
||||
git checkout feature/mein-kaputter-branch
|
||||
git merge main
|
||||
# (Das holt die fehlenden Dateien aus main nach)
|
||||
@@ -1,9 +1,9 @@
|
||||
# Mindnet v2.2 – Fachliche Architektur
|
||||
**Datei:** `docs/mindnet_functional_architecture_v2.2.md`
|
||||
**Stand:** 2025-12-07
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP04a)
|
||||
**Stand:** 2025-12-08
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP04c)
|
||||
|
||||
> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten) zwischen Notizen/Chunks sowie die Logik des Retrievers. Die technische Umsetzung (Module, Flags, Schemas) wird im technischen Dokument detailliert.
|
||||
> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten) zwischen Notizen/Chunks sowie die Logik des Retrievers und der Feedback-Mechanismen. Die technische Umsetzung wird im technischen Dokument detailliert.
|
||||
|
||||
---
|
||||
|
||||
@@ -134,7 +134,7 @@ Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. *
|
||||
|
||||
## 5) Der Retriever (Funktionaler Layer)
|
||||
|
||||
Der Retriever ist in v2.2 der zentrale Zugangspunkt zum Wissen. Er realisiert die **Hybride Suche**.
|
||||
Der Retriever ist in v2.2 der zentrale Zugangspunkt. Er realisiert die **Hybride Suche**.
|
||||
|
||||
### 5.1 Scoring-Modell
|
||||
Die Relevanz eines Treffers ergibt sich nicht mehr nur aus Textähnlichkeit, sondern aus einer gewichteten Formel:
|
||||
@@ -147,17 +147,45 @@ Die Relevanz eines Treffers ergibt sich nicht mehr nur aus Textähnlichkeit, son
|
||||
|
||||
* **semantic_score:** Vektorähnlichkeit (Qdrant).
|
||||
* **retriever_weight:** Wichtigkeit des Typs (z.B. Projekte > Quellen).
|
||||
* **edge_bonus:** Belohnung für Chunks, die im Kontext der Anfrage stark vernetzt sind (unter Berücksichtigung der *confidence*).
|
||||
* **edge_bonus:** Belohnung für Chunks, die im Kontext der Anfrage stark vernetzt sind (Summe der Confidence eingehender relevanter Kanten).
|
||||
* **centrality_bonus:** Belohnung für Knoten, die zentrale Hubs im lokalen Graphen darstellen.
|
||||
|
||||
### 5.2 Erklärbarkeit (Explainability)
|
||||
Der Retriever liefert **Begründungspfade**. Er gibt nicht nur Text zurück, sondern:
|
||||
* `score_breakdown`: Warum ist dieser Chunk oben? (War es der Text oder der Graph?)
|
||||
* `paths`: Über welche Kanten wurde dieser Chunk gefunden? (z.B. "Gefunden via `depends_on` von deiner aktuellen Projekt-Notiz").
|
||||
### 5.2 Erklärbarkeit (Explainability) – WP04b
|
||||
Der Retriever ist keine Blackbox mehr. Er liefert auf Wunsch (`explain=True`) eine strukturierte Begründung (`Explanation`-Objekt).
|
||||
|
||||
**Die "Warum"-Logik:**
|
||||
1. **Semantik:** Prüfung der Cosine-Similarity ("Sehr hohe textuelle Übereinstimmung").
|
||||
2. **Typ:** Prüfung des `retriever_weight` ("Bevorzugt, da Entscheidung").
|
||||
3. **Graph (Kontext):**
|
||||
* **Hub (Outgoing):** Worauf verweist dieser Treffer? ("Verweist auf Qdrant").
|
||||
* **Authority (Incoming):** Wer verweist auf diesen Treffer? ("Wird referenziert von Projekt Alpha").
|
||||
|
||||
Die API gibt diese Analysen als menschenlesbare Sätze (`reasons`) und als Datenstruktur (`score_breakdown`) zurück.
|
||||
|
||||
---
|
||||
|
||||
## 6) Confidence & Provenance – wozu?
|
||||
## 6) Feedback & Lernen – WP04c
|
||||
|
||||
Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, das die Basis für zukünftiges Lernen bildet.
|
||||
|
||||
### 6.1 Der Feedback-Loop
|
||||
1. **Suche (Situation):**
|
||||
Wenn ein Nutzer eine Anfrage stellt, loggt Mindnet die "Situation":
|
||||
* Den Query-Text.
|
||||
* Die Top-K Ergebnisse.
|
||||
* Den exakten `score_breakdown` zu diesem Zeitpunkt.
|
||||
* Eine eindeutige `query_id` wird generiert.
|
||||
|
||||
2. **Bewertung (Label):**
|
||||
Der Nutzer (oder ein Agent) bewertet einen spezifischen Treffer (`node_id`) positiv oder negativ (Score 1-5).
|
||||
Dieses Feedback wird unter Referenzierung der `query_id` gespeichert.
|
||||
|
||||
3. **Lernen (Perspektive WP08):**
|
||||
Durch die Verknüpfung von Situation und Bewertung entstehen Trainingsdaten. Mindnet kann später analysieren: *"Nutzer bevorzugen Treffer mit hohem Edge-Bonus, auch wenn der Text weniger passt."* -> Konsequenz: `edge_weight` erhöhen.
|
||||
|
||||
---
|
||||
|
||||
## 7) Confidence & Provenance – wozu?
|
||||
|
||||
Der Retriever kann Edges gewichten:
|
||||
- **provenance**: *explicit* > *rule*
|
||||
@@ -169,7 +197,7 @@ Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
|
||||
|
||||
---
|
||||
|
||||
## 7) Semantik ausgewählter `kind`-Werte
|
||||
## 8) Semantik ausgewählter `kind`-Werte
|
||||
|
||||
- `references` – „Nutzt/erwähnt“; neutral, aber stützend für Kontext.
|
||||
- `related_to` – Ähnlichkeit/Verwandtschaft (symmetrisch interpretierbar).
|
||||
@@ -181,7 +209,7 @@ Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
|
||||
|
||||
---
|
||||
|
||||
## 8) Frontmatter-Eigenschaften – Rolle & Empfehlung
|
||||
## 9) Frontmatter-Eigenschaften – Rolle & Empfehlung
|
||||
|
||||
Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
|
||||
- **type** – steuert Typ-Defaults via Registry (Pflicht für differenziertes Verhalten).
|
||||
@@ -191,7 +219,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
|
||||
|
||||
---
|
||||
|
||||
## 9) Lösch-/Update-Garantien (Idempotenz)
|
||||
## 10) Lösch-/Update-Garantien (Idempotenz)
|
||||
|
||||
- Jede Note hat einen stabilen **note_id** (Frontmatter/Hash).
|
||||
- Vor einem Upsert können *alte Chunks/Edges einer Note* gefiltert gelöscht werden (`note_id`-Filter) – das hält Collections sauber bei Re-Imports.
|
||||
@@ -199,7 +227,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
|
||||
|
||||
---
|
||||
|
||||
## 10) Beispiel – Von Markdown zu Kanten (v2.2)
|
||||
## 11) Beispiel – Von Markdown zu Kanten (v2.2)
|
||||
|
||||
**Markdown (Auszug)**
|
||||
# Relations Showcase
|
||||
@@ -218,7 +246,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
|
||||
|
||||
---
|
||||
|
||||
## 11) Qualitäts- und Testkriterien (fachlich)
|
||||
## 12) Qualitäts- und Testkriterien (fachlich)
|
||||
|
||||
- **Keine Duplikate** gleicher `(src, relation, dst)` in der Collectionsicht (Dedup).
|
||||
- **Explizite Links** werden vollständig materialisiert (*explicit_total*).
|
||||
@@ -227,9 +255,10 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
|
||||
|
||||
---
|
||||
|
||||
## 12) Referenzen (Projektdateien & Leitlinien)
|
||||
## 13) Referenzen (Projektdateien & Leitlinien)
|
||||
|
||||
- Import-Pipeline & Registry-Auflösung: `scripts/import_markdown.py`.
|
||||
- Kantenbildung (V2-Logic): `app/core/derive_edges.py`.
|
||||
- Typ-Registry: `config/types.yaml` & `TYPE_REGISTRY_MANUAL.md`.
|
||||
- Retriever-Scoring: `app/core/retriever.py` & `wp04_retriever_scoring.md`.
|
||||
- Retriever-Scoring & Explanation: `app/core/retriever.py`.
|
||||
- Logging Service: `app/services/feedback_service.py`.
|
||||
@@ -1,8 +1,8 @@
|
||||
# Mindnet v2.2 – Technische Architektur
|
||||
**Datei:** `docs/mindnet_technical_architecture_v2.2.md`
|
||||
**Stand:** 2025-12-07
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP04a)
|
||||
**Quellen:** `mindnet_technical_architecture.md`, `chunking_strategy.md`, `Handbuch.md`, `wp04_retriever_scoring.md`, `Überarbeitungshinweise_WP03.md`, `Überarbeitungshinweise_WP04.md`.
|
||||
**Stand:** 2025-12-08
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP04c)
|
||||
**Quellen:** `mindnet_technical_architecture.md`, `chunking_strategy.md`, `Handbuch.md`, `wp04_retriever_scoring.md`.
|
||||
|
||||
> **Ziel dieses Dokuments:**
|
||||
> Vollständige, konsolidierte Beschreibung der aktuellen technischen Architektur von **Mindnet v2.2**. Es definiert die Datenstrukturen in Qdrant, die Verarbeitungspipelines (Importer, Chunker, Edges) und die Retrieval-Logik. Es bildet den **aktuellen Implementierungsstand** ab.
|
||||
@@ -15,8 +15,10 @@
|
||||
Mindnet ist ein **persönliches Wissensnetz**. Technisch bedeutet das:
|
||||
1. **Source:** Markdown-Notizen in einem Vault (Obsidian-kompatibel).
|
||||
2. **Pipeline:** Ein Python-Importer transformiert diese in **Notes**, **Chunks** und **Edges**.
|
||||
3. **Storage:** Speicherung in **Qdrant** (Vektor-Datenbank) in drei getrennten Collections.
|
||||
4. **Service:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** bereit.
|
||||
3. **Storage:**
|
||||
* **Qdrant:** Vektor-Datenbank für Graph und Semantik (Collections: notes, chunks, edges).
|
||||
* **Local Files (JSONL):** Append-Only Logs für Feedback und Search-History (Data Flywheel).
|
||||
4. **Service:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** sowie **Feedback** bereit.
|
||||
|
||||
Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsgetrieben** (`types.yaml`, `retriever.yaml`).
|
||||
|
||||
@@ -34,12 +36,21 @@ Die Codebasis ist modular aufgebaut.
|
||||
│ │ ├── chunker.py # Text-Zerlegung (Profiling)
|
||||
│ │ ├── edges.py # Edge-Datenstrukturen
|
||||
│ │ ├── derive_edges.py # Logik der Kantenableitung (WP03)
|
||||
│ │ └── retriever.py # Scoring & Graph-Expansion (WP04)
|
||||
│ ├── models/ # Pydantic DTOs (QueryRequest, etc.)
|
||||
│ └── routers/ # API Routen
|
||||
│ │ ├── graph_adapter.py # Subgraph & Reverse-Lookup (WP04b)
|
||||
│ │ └── retriever.py # Scoring, Expansion & Explanation (WP04a/b)
|
||||
│ ├── models/ # Pydantic DTOs (QueryHit, Explanation, FeedbackRequest)
|
||||
│ ├── routers/
|
||||
│ │ ├── query.py # Such-Endpunkt
|
||||
│ │ ├── feedback.py # Feedback-Endpunkt (WP04c)
|
||||
│ │ └── ...
|
||||
│ ├── services/
|
||||
│ │ ├── feedback_service.py # Logging-Logik (WP04c)
|
||||
│ │ └── embeddings_client.py
|
||||
├── config/
|
||||
│ ├── types.yaml # Typ-Definitionen (Import-Zeit)
|
||||
│ └── retriever.yaml # Scoring-Gewichte (Laufzeit)
|
||||
├── data/
|
||||
│ └── logs/ # Lokale JSONL-Logs (WP04c)
|
||||
├── scripts/
|
||||
│ ├── import_markdown.py # Haupt-Importer CLI
|
||||
│ ├── payload_dryrun.py # Diagnose: JSON-Generierung ohne DB
|
||||
@@ -69,8 +80,6 @@ Repräsentiert die Metadaten einer Datei.
|
||||
| `updated` | Integer | Zeitstempel (z.B. YYYYMMDD...). | File Stats |
|
||||
| `fulltext` | Text | Gesamter Inhalt (für Export/Rekonstruktion). | Body |
|
||||
|
||||
|
||||
|
||||
### 2.2 Chunks Collection (`<prefix>_chunks`)
|
||||
Die atomaren Sucheinheiten.
|
||||
* **Zweck:** Vektorsuche (Embeddings), Granulares Ergebnis.
|
||||
@@ -88,8 +97,6 @@ Die atomaren Sucheinheiten.
|
||||
| `neighbors_prev` | List[Str] | ID des Vorgänger-Chunks. |
|
||||
| `neighbors_next` | List[Str] | ID des Nachfolger-Chunks. |
|
||||
|
||||
|
||||
|
||||
### 2.3 Edges Collection (`<prefix>_edges`)
|
||||
Gerichtete Kanten. Massiv erweitert in WP03 für Provenienz-Tracking.
|
||||
* **Zweck:** Graph-Traversal, Kontext-Anreicherung.
|
||||
@@ -106,8 +113,6 @@ Gerichtete Kanten. Massiv erweitert in WP03 für Provenienz-Tracking.
|
||||
| `rule_id` | Keyword | Herkunftsregel. | `explicit:wikilink`, `inline:rel` |
|
||||
| `confidence` | Float | Vertrauenswürdigkeit (0.0-1.0). | 1.0, 0.95, 0.7 |
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 3. Konfiguration
|
||||
@@ -185,12 +190,44 @@ $$
|
||||
* $B_{cent}$: Centrality-Bonus (im lokalen Subgraphen).
|
||||
* **Gewichte ($W$):** Stammen aus `retriever.yaml`.
|
||||
|
||||
### 5.3 Graph-Expansion
|
||||
Der Hybrid-Modus lädt dynamisch die Nachbarschaft der Top-K Vektor-Treffer ("Seeds") über `graph_adapter.expand`. Dies baut einen temporären `NetworkX`-Graphen im Speicher, auf dem Boni berechnet werden.
|
||||
### 5.3 Explanation Layer (WP04b)
|
||||
Der Retriever kann Ergebnisse erklären (`explain=True`).
|
||||
* **Logik:**
|
||||
* Berechnung des `ScoreBreakdown` (Anteile von Semantik, Graph, Typ).
|
||||
* Analyse des lokalen Subgraphen mittels `graph_adapter.py`.
|
||||
* **Incoming Edges (Authority):** Wer zeigt auf diesen Treffer? (z.B. "Referenziert von...")
|
||||
* **Outgoing Edges (Hub):** Worauf zeigt dieser Treffer? (z.B. "Verweist auf...")
|
||||
* **Output:** `QueryHit` enthält ein `explanation` Objekt mit menschenlesbaren `reasons` und `related_edges`.
|
||||
|
||||
### 5.4 Graph-Expansion
|
||||
Der Hybrid-Modus lädt dynamisch die Nachbarschaft der Top-K Vektor-Treffer ("Seeds") über `graph_adapter.expand`. Dies baut einen temporären `NetworkX`-artigen Graphen im Speicher (Klasse `Subgraph`), auf dem Boni berechnet werden.
|
||||
|
||||
---
|
||||
|
||||
## 6. Indizes & Performance
|
||||
## 6. Feedback & Logging Architektur (WP04c)
|
||||
|
||||
Mindnet implementiert ein "Data Flywheel" zur späteren Optimierung (Self-Tuning).
|
||||
|
||||
### 6.1 Komponenten
|
||||
* **Feedback Service (`app/services/feedback_service.py`):** Kapselt die Schreibzugriffe.
|
||||
* **Storage:** Lokales Dateisystem (`data/logs/`), Format JSONL (Line-delimited JSON).
|
||||
|
||||
### 6.2 Log-Dateien
|
||||
1. **`search_history.jsonl`**:
|
||||
* Speichert jede Anfrage an `/query`.
|
||||
* Enthält: `query_id`, `query_text`, `timestamp`, `hits` (inkl. `score_breakdown` Snapshots).
|
||||
* Zweck: Trainingsdaten ("Was hat das System gesehen?").
|
||||
2. **`feedback.jsonl`**:
|
||||
* Speichert User-Reaktionen an `/feedback`.
|
||||
* Enthält: `query_id`, `node_id`, `score` (1-5), `comment`.
|
||||
* Zweck: Labels ("War es gut?").
|
||||
|
||||
### 6.3 Traceability
|
||||
Die `query_id` (UUIDv4) wird im `/query` Response generiert und muss vom Client beim `/feedback` Aufruf mitgesendet werden. Dies ermöglicht den Join zwischen Snapshot und Bewertung.
|
||||
|
||||
---
|
||||
|
||||
## 7. Indizes & Performance
|
||||
|
||||
Damit Qdrant performant bleibt, sind Payload-Indizes essenziell.
|
||||
|
||||
@@ -203,7 +240,7 @@ Validierung erfolgt über `tests/ensure_indexes_and_show.py`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Offene Punkte / Known Limitations
|
||||
## 8. Offene Punkte / Known Limitations
|
||||
|
||||
1. **Multi-Target Inline-Relations:**
|
||||
* `rel: similar_to [[A]] [[B]]` wird aktuell parser-seitig nicht unterstützt.
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
import requests
|
||||
import json
|
||||
import sys
|
||||
import time
|
||||
|
||||
# Konfiguration
|
||||
BASE_URL = "http://localhost:8001"
|
||||
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()
|
||||
Reference in new issue
Block a user