Compare commits

..
Author SHA1 Message Date
Lars ba57e8b43f Merge pull request 'WP10' (#6) from WP10 into main
Deploy mindnet to llm-node / deploy (push) Successful in 12s
Reviewed-on: #6
# Merge Request: WP-10 (Chat Interface & Frontend Architecture)

**Branch:** `feature/WP10-chat-interface` → `main`
**Status:** ✅ Ready for Merge
**Version Bump:** v2.3.1 → v2.3.2

## Zusammenfassung
Dieser Merge führt das **Web-Frontend (Streamlit)** ein. Damit wird Mindnet von einer reinen Terminal-Applikation zu einem interaktiven System mit grafischer Benutzeroberfläche.
Das Frontend visualisiert die Entscheidungen der **Decision Engine** (WP-06) und ermöglicht strukturiertes Feedback für das zukünftige **Self-Tuning** (WP-08).

## 🚀 Neue Features (User Perspective)
* **Web Chat UI:** ChatGPT-ähnliches Interface mit persistenter History.
* **Intent Visualisierung:** Badges zeigen an, in welchem Modus (FACT, DECISION, EMPATHY) das System antwortet und *warum* (Keyword vs. LLM).
* **Transparent Sources:** Verwendete Quellen werden als expandierbare Karten unter der Antwort angezeigt, inkl. "Why"-Erklärung.
* **Feedback Loop:**
    * **Global (Antwort):** 1-5 Sterne Rating.
    * **Granular (Quellen):** Faces-Rating (Mapped auf Score 1-5) für spezifische Chunks.

## 🛠️ Technische Änderungen (Backend/Infra)
* **Neue Komponente:** `app/frontend/ui.py` (Streamlit App).
* **Dependencies:** `streamlit` zu `requirements.txt` hinzugefügt.
* **Deployment:** Konfiguration für getrennte Services in Prod und Dev:
    * **PROD:** Backend `:8001` ↔ Frontend `:8501`
    * **DEV:** Backend `:8002` ↔ Frontend `:8502`
* **Logging:** Integration der Feedback-Logik in `data/logs/feedback.jsonl`.

## ⚠️ Deployment Hinweise
Nach dem Merge müssen auf dem Server folgende Schritte ausgeführt werden:

1.  **Dependencies:** `pip install -r requirements.txt` (für Streamlit).
2.  **Systemd:** Neue Service-Files für die UI anlegen (`mindnet-ui-prod.service`).
3.  **Firewall:** Port `8501` (Prod) und `8502` (Dev) in `ufw` freigeben.

## Checkliste
- [x] UI startet und verbindet sich mit API.
- [x] Chat-Flow (Request/Response) funktioniert.
- [x] Intent-Badge zeigt korrekte Source an.
- [x] Feedback wird in `feedback.jsonl` geschrieben.
- [x] Dokumentation (Admin Guide, User Guide, Arch) ist aktualisiert.
2025-12-10 10:29:10 +01:00
Lars be406d230f Dokumentation WP10 2025-12-10 10:26:44 +01:00
Lars 38abde8516 Gui Anpassung. 2025-12-09 23:16:28 +01:00
Lars 9bb6566419 kleine Änderungen 2025-12-09 23:12:07 +01:00
Lars 2acaf3c060 vorbereitung UI für WP07 2025-12-09 23:05:28 +01:00
Lars ec33163d98 verbessertes Feedback 2025-12-09 22:43:38 +01:00
Lars 2d0913cf3b Feedback UI 2025-12-09 22:27:56 +01:00
Lars 76ea8e3350 Update für Feedback Loop 2025-12-09 22:07:58 +01:00
Lars bbc1e589f5 Nutzung von .env für Timeout 2025-12-09 19:00:39 +01:00
Lars 987e297c07 Erste Version Wp10 2025-12-09 18:44:26 +01:00
Lars 046aa2cf48 Merge pull request 'WP06a' (#5) from WP06a into main
Deploy mindnet to llm-node / deploy (push) Successful in 4s
Reviewed-on: #5
fix(wp06a): Fix API Payload-Enrichment & CPU Timeouts

Stabilisierungspatch für die Decision Engine (Post-WP06).

**Bugfixes & Verbesserungen:**
- **FIX:** API (Retriever) liefert nun `payload`-Daten im `QueryHit` zurück. Behebt "Typ: unknown" Fehler in Clients/Tests.
- **FIX:** Test-Skript (`test_wp06_decision.py`) prüft nun robust auf `payload` oder `source` und zeigt Intent-Source an.
- **FIX:** Timeout für LLM-Inference in `.env` konfigurierbar gemacht (`MINDNET_LLM_TIMEOUT`) und Default für Tests auf 300s erhöht (Cold-Start Protection).
- **CHORE:** DTOs erweitert um `intent_source` für besseres Tracing (Keyword vs. LLM).
- **DOCS:** Technische Architektur und Appendices aktualisiert (Chunk-Schema enthält nun explizit `type`).

**Version Bump:** v2.3.1 -> v2.3.2
2025-12-09 18:25:36 +01:00
Lars 0bc0e66a85 Dokumentation angepasst 2025-12-09 18:22:15 +01:00
Lars 2310633de3 payload durchreichen bis zum chat 2025-12-09 18:11:25 +01:00
Lars bd36d78025 neue Test 2025-12-09 18:02:21 +01:00
Lars d2270fafdd testscript für WP06 korrigiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-09 17:45:08 +01:00
18 changed files with 746 additions and 302 deletions

No files matched your search

+47 -20
View File
@@ -1,6 +1,6 @@
# mindnet v2.2 — Programmplan
**Version:** 2.3.1 (Post-WP06 Decision Engine)
**Stand:** 2025-12-09
**Version:** 2.3.2 (Inkl. WP-10a GUI Evolution)
**Stand:** 2025-12-10
**Status:** Aktiv
---
@@ -27,7 +27,8 @@
- [WP-07 – Interview-Assistent (geplant)](#wp-07--interview-assistent-geplant)
- [WP-08 – Self-Tuning v1/v2 (geplant)](#wp-08--self-tuning-v1v2-geplant)
- [WP-09 – Vault-Onboarding \& Migration (geplant)](#wp-09--vault-onboarding--migration-geplant)
- [WP-10 – Chat-Interface \& Writeback (geplant)](#wp-10--chat-interface--writeback-geplant)
- [WP-10 – Chat-Interface \& Writeback (abgeschlossen)](#wp-10--chat-interface--writeback-abgeschlossen)
- [WP-10a – GUI Evolution: Interaktion \& Tools (geplant)](#wp-10a--gui-evolution-interaktion--tools-geplant)
- [WP-11 – Knowledge-Builder \& Vernetzungs-Assistent (geplant)](#wp-11--knowledge-builder--vernetzungs-assistent-geplant)
- [WP-12 – Knowledge Rewriter (Soft Mode, geplant)](#wp-12--knowledge-rewriter-soft-mode-geplant)
- [WP-13 – MCP-Integration \& Agenten-Layer (geplant)](#wp-13--mcp-integration--agenten-layer-geplant)
@@ -115,7 +116,8 @@ Kernprinzipien der Vision:
- **RAG-Chat:** KI antwortet in natürlicher Sprache auf Basis von Wissen und Persönlichkeit (WP-05 abgeschlossen).
- **Decision Engine:** System erkennt Intent (Fakt vs. Entscheidung) und wägt Werte ab (WP-06 abgeschlossen).
- **Multi-Persona:** System wechselt den Tonfall (Empathisch vs. Analytisch) situativ (WP-06 abgeschlossen).
- Technische Basis: FastAPI, Qdrant, Ollama (Local LLM).
- **Chat Interface:** Web-basiertes Frontend (Streamlit) für einfache Interaktion und Feedback-Gabe (WP-10 abgeschlossen).
- Technische Basis: FastAPI, Qdrant, Ollama (Local LLM), Streamlit.
- Automatisierte Erkennung von Beziehungen:
- Wikilinks, Inline-Relationen, Callout-Edges, Typ-Defaults.
- „Mitwachsendes“ Schema ohne Obsidian-Umstrukturierungen:
@@ -124,10 +126,10 @@ Kernprinzipien der Vision:
### 3.2 Mittelfristig (Nächste Schritte)
- **Chat Interface (WP-10):** Ablösung der Terminal-Interaktion durch ein Web-Frontend (Streamlit/React) für bessere UX und einfacheres Feedback-Geben.
- Interview-Assistent erstellt neue Notes automatisch (strukturierte Dialoge → Markdown).
- **Interview-Assistent (WP-07):** Geführte Dialoge zur Erfassung neuer Notizen (Startbereit).
- mindnet erzeugt Vorschläge für neue Notes & Edges und bietet einen „Vernetzungs-Assistenten“ für manuell angelegte Notizen.
- Agenten können über MCP-Tools (`mindnet_query`, `mindnet_chat`) auf mindnet zugreifen.
- Self-Tuning optimiert die Gewichte in `retriever.yaml` basierend auf dem gesammelten Feedback (WP-08).
### 3.3 Langfristig
@@ -189,10 +191,10 @@ Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen:
Phase A – Fundament & Import (Fertig)
Phase B – Semantik, Graph & Lernen (Fertig)
Phase C – Persönlichkeitsmodell & KI-Zwilling (Fertig)
Phase D – Agenten, MCP & Interaktion (Startend)
Phase D – Agenten, MCP & Interaktion (Laufend)
Phase E – Review, Refactoring, Dokumentation
Alle Workpackages sind einer Phase zugeordnet. WP-01 bis WP-06 sind bereits erfolgreich abgeschlossen.
Alle Workpackages sind einer Phase zugeordnet. WP-01 bis WP-06 und WP-10 sind bereits erfolgreich abgeschlossen.
---
@@ -354,15 +356,15 @@ Transformation vom reinen Wissens-Abrufer zum strategischen Entscheidungspartner
### WP-07 – Interview-Assistent (geplant)
**Phase:** C
**Status:** 🟡 geplant
**Phase:** C/D
**Status:** 🟡 geplant (Nächster Fokus)
**Ziel:**
Dialogbasierter Erfassungs-Assistent, der strukturierte Interviews führt und daraus konsistente Markdown-Notizen generiert.
**Umfang:**
- Design von Interview-Flows.
- Konvertierung von Dialogtranskripten in typisierte Notes.
- Design von Interview-Flows (via Router-Strategie `INTERVIEW`).
- Konvertierung von Dialogtranskripten in typisierte Notes (Draft-Erstellung).
**Aufwand / Komplexität:**
- Aufwand: Niedrig/Mittel
@@ -406,25 +408,46 @@ Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet
---
### WP-10 – Chat-Interface & Writeback (geplant)
### WP-10 – Chat-Interface & Writeback (abgeschlossen)
**Phase:** D
**Status:** 🟡 geplant (Priorität B - "Quick Win")
**Status:** 🟢 abgeschlossen
**Ziel:**
Ablösung der Terminal-Interaktion durch ein grafisches Interface.
**Umfang:**
- Technologie: Streamlit oder einfaches HTML/JS Frontend.
- Funktionen: Chat-Verlauf, Anzeige der Quellen (mit Scores), Daumen-hoch/runter für WP-04c Feedback.
- Funktionen für Q&A sowie Vorschlag neuer Notes/Edges.
**Erreichte Ergebnisse:**
- **Tech-Stack:** Streamlit Frontend (`app/frontend/ui.py`).
- **Funktionen:** Chat-Verlauf, Visualisierung von Intents und Quellen (Expander).
- **Feedback:** Globales Rating (Sterne) und granulare Quellen-Bewertung (Faces).
- **Writeback:** Mockup-Interface für neue Einträge (Vorbereitung WP-07).
- **Deployment:** Systemd-Services für Prod (8501) und Dev (8502).
**Aufwand / Komplexität:**
- Aufwand: Hoch (durch Writeback) / Mittel (für reines Frontend)
- Aufwand: Hoch
- Komplexität: Hoch
---
### WP-10a – GUI Evolution: Interaktion & Tools (geplant)
**Phase:** D
**Status:** 🟡 geplant (nach WP07/11)
**Ziel:**
Anpassung der GUI an komplexe Interaktionsmuster, die durch den Interview-Assistenten und Knowledge-Builder entstehen.
**Umfang:**
- **Draft-Editor:** Interaktive Bearbeitung und Bestätigung der Markdown-Entwürfe aus WP-07.
- **Suggestion-UI:** Checkboxen/Toggles für Kanten-Vorschläge aus WP-11 (Human-in-the-Loop).
- **Writeback:** Physisches Speichern der bestätigten Inhalte im Vault.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel
---
### WP-11 – Knowledge-Builder & Vernetzungs-Assistent (geplant)
**Phase:** D
@@ -489,6 +512,7 @@ Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritte
WP01 → WP02 → WP03 → WP04a
WP04a → WP04b → WP04c → WP08
WP03 → WP05 → WP06 → WP07
WP07/WP11 → WP10a
WP03 → WP09
WP01/WP03 → WP10 → WP11 → WP12
WP03/WP04 → WP13
@@ -508,6 +532,7 @@ Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritte
| WP08 | Hoch | Hoch |
| WP09 | Mittel | Niedrig/Mittel |
| WP10 | Hoch | Hoch |
| WP10a | Mittel | Mittel |
| WP11 | Hoch | Hoch |
| WP12 | Niedrig/Mittel | Mittel |
| WP13 | Mittel | Mittel |
@@ -531,7 +556,8 @@ Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritte
| WP07 | 🟡 |
| WP08 | 🟡 |
| WP09 | 🟡 |
| WP10 | 🟡 |
| WP10 | 🟢 |
| WP10a | 🟡 |
| WP11 | 🟡 |
| WP12 | 🟡 |
| WP13 | 🟡 |
@@ -559,6 +585,7 @@ mindnet v2.2 ist so aufgesetzt, dass:
- ein **hybrider Retriever** qualitativ hochwertige, erklärbare Antworten liefert,
- ein **Self-Healing- und Self-Tuning-Mechanismus** vorbereitet ist (durch WP-04c Feedback-Daten),
- ein **Persönlichkeitsmodell** (Decision Engine, Empathie) existiert und den Tonfall situativ anpasst,
- eine **grafische Oberfläche** (WP-10) existiert, die komplexe Zusammenhänge (Intents, Quellen) visualisiert,
- langfristig ein **KI-Zwilling** aufgebaut wird, der deine Werte, Erfahrungen und Denkweise spiegelt,
- die technische Architektur (FastAPI, Qdrant, YAML-Policies, MCP-Integration) lokal, nachvollziehbar und erweiterbar bleibt.
+10 -7
View File
@@ -2,7 +2,7 @@
app/core/retriever.py — Hybrider Such-Algorithmus
Version:
0.5.2 (WP-05 Fix: Pass content in QueryHit source)
0.5.3 (WP-06 Fix: Populate 'payload' in QueryHit for meta-data access)
"""
from __future__ import annotations
@@ -127,7 +127,9 @@ def _build_explanation(
node_key: Optional[str]
) -> Explanation:
"""Erstellt ein Explanation-Objekt."""
sem_w, edge_w, cent_w = _get_scoring_weights()
sem_w, _edge_w, _cent_w = _get_scoring_weights()
# Scoring weights erneut laden für Reason-Details
_, edge_w_cfg, cent_w_cfg = _get_scoring_weights()
try:
type_weight = float(payload.get("retriever_weight", 1.0))
@@ -138,8 +140,8 @@ def _build_explanation(
breakdown = ScoreBreakdown(
semantic_contribution=(sem_w * semantic_score * type_weight),
edge_contribution=(edge_w * edge_bonus),
centrality_contribution=(cent_w * cent_bonus),
edge_contribution=(edge_w_cfg * edge_bonus),
centrality_contribution=(cent_w_cfg * cent_bonus),
raw_semantic=semantic_score,
raw_edge_bonus=edge_bonus,
raw_centrality=cent_bonus,
@@ -179,7 +181,7 @@ def _build_explanation(
all_edges = sorted(edges_dto, key=lambda e: e.weight, reverse=True)
for top_edge in all_edges[:3]:
impact = edge_w * top_edge.weight
impact = edge_w_cfg * top_edge.weight
dir_txt = "Verweist auf" if top_edge.direction == "out" else "Referenziert von"
tgt_txt = top_edge.target if top_edge.direction == "out" else top_edge.source
reasons.append(Reason(kind="edge", message=f"{dir_txt} '{tgt_txt}' via '{top_edge.kind}'", score_impact=impact, details={"kind": top_edge.kind}))
@@ -261,7 +263,6 @@ def _build_hits_from_semantic(
node_key=payload.get("chunk_id") or payload.get("note_id")
)
# FIX: Hier holen wir jetzt den Textinhalt (text, content oder page_content) aus dem Payload
text_content = payload.get("page_content") or payload.get("text") or payload.get("content")
results.append(QueryHit(
@@ -275,8 +276,10 @@ def _build_hits_from_semantic(
source={
"path": payload.get("path"),
"section": payload.get("section") or payload.get("section_title"),
"text": text_content # WICHTIG: Inhalt durchreichen
"text": text_content
},
# --- FIX: Wir füllen das payload-Feld explizit ---
payload=payload,
explanation=explanation_obj
))
+207
View File
@@ -0,0 +1,207 @@
import streamlit as st
import requests
import uuid
import os
import json
from pathlib import Path
from dotenv import load_dotenv
# --- CONFIGURATION ---
load_dotenv()
API_BASE_URL = os.getenv("MINDNET_API_URL", "http://localhost:8002")
CHAT_ENDPOINT = f"{API_BASE_URL}/chat"
FEEDBACK_ENDPOINT = f"{API_BASE_URL}/feedback"
HISTORY_FILE = Path("data/logs/search_history.jsonl")
# Timeout Strategy
timeout_setting = os.getenv("MINDNET_API_TIMEOUT") or os.getenv("MINDNET_LLM_TIMEOUT")
API_TIMEOUT = float(timeout_setting) if timeout_setting else 300.0
# --- PAGE SETUP ---
st.set_page_config(page_title="mindnet v2.3.1", page_icon="🧠", layout="wide")
# --- CSS STYLING ---
st.markdown("""
<style>
/* Hauptcontainer enger machen für Lesbarkeit */
.block-container { padding-top: 2rem; max_width: 900px; margin: auto; }
/* Intent Badges */
.intent-badge {
background-color: #e8f0fe; color: #1a73e8;
padding: 4px 10px; border-radius: 12px;
font-size: 0.8rem; font-weight: 600;
border: 1px solid #d2e3fc; display: inline-block; margin-bottom: 0.5rem;
}
/* Chat Message Styling */
.stChatMessage { padding: 1rem; border-radius: 8px; margin-bottom: 1rem;}
div[data-testid="stChatMessageContent"] p { font-size: 1.05rem; line-height: 1.6; }
/* Expander Cleaner */
.streamlit-expanderHeader { font-size: 0.9rem; font-weight: 600; color: #444; }
</style>
""", unsafe_allow_html=True)
# --- SESSION STATE ---
if "messages" not in st.session_state: st.session_state.messages = []
if "user_id" not in st.session_state: st.session_state.user_id = str(uuid.uuid4())
if "draft_note" not in st.session_state: st.session_state.draft_note = {"title": "", "content": "", "type": "concept"}
# --- HELPER FUNCTIONS ---
def load_history_from_logs(limit=10):
"""Liest die letzten N Queries aus dem Logfile."""
queries = []
if HISTORY_FILE.exists():
try:
with open(HISTORY_FILE, "r", encoding="utf-8") as f:
lines = f.readlines()
for line in reversed(lines):
try:
entry = json.loads(line)
q = entry.get("query_text")
if q and q not in queries:
queries.append(q)
if len(queries) >= limit: break
except: continue
except Exception as e:
st.sidebar.warning(f"Log-Fehler: {e}")
return queries
def send_chat_message(message: str, top_k: int, explain: bool):
try:
response = requests.post(
CHAT_ENDPOINT,
json={"message": message, "top_k": top_k, "explain": explain},
timeout=API_TIMEOUT
)
response.raise_for_status()
return response.json()
except Exception as e:
return {"error": str(e)}
def submit_feedback(query_id, node_id, score, comment=None):
try:
requests.post(FEEDBACK_ENDPOINT, json={"query_id": query_id, "node_id": node_id, "score": score, "comment": comment}, timeout=2)
target = "Antwort" if node_id == "generated_answer" else "Quelle"
st.toast(f"Feedback für {target} gespeichert! (Score: {score})")
except: pass
# --- UI COMPONENTS ---
def render_sidebar():
with st.sidebar:
st.title("🧠 mindnet")
st.caption("v2.3.1 | WP-10 UI")
mode = st.radio("Modus", ["💬 Chat", "📝 Neuer Eintrag (WP-07)"], index=0)
st.divider()
st.subheader("⚙️ Settings")
top_k = st.slider("Quellen (Top-K)", 1, 10, 5)
explain = st.toggle("Explanation Layer", True)
st.divider()
st.subheader("🕒 Verlauf")
history = load_history_from_logs(8)
if not history:
st.caption("Noch keine Einträge.")
for q in history:
if st.button(f"🔎 {q[:30]}...", key=f"hist_{q}", help=q, use_container_width=True):
st.session_state.messages.append({"role": "user", "content": q})
st.rerun()
return mode, top_k, explain
def render_chat_interface(top_k, explain):
# Render History
for msg in st.session_state.messages:
with st.chat_message(msg["role"]):
if msg["role"] == "assistant":
# Intent Badge MIT SOURCE (Fix für Debugging)
if "intent" in msg:
icon = {"EMPATHY": "❤️", "DECISION": "⚖️", "CODING": "💻", "FACT": "📚"}.get(msg["intent"], "🧠")
source_info = msg.get("intent_source", "Unknown")
# Hier wird die Quelle wieder angezeigt:
st.markdown(f'<div class="intent-badge">{icon} Intent: {msg["intent"]} <span style="opacity:0.6; font-size: 0.9em; margin-left:5px;">via {source_info}</span></div>', unsafe_allow_html=True)
st.markdown(msg["content"])
# Sources
if "sources" in msg:
for hit in msg["sources"]:
score = hit.get('total_score', 0)
icon = "🟢" if score > 0.8 else "🟡" if score > 0.5 else "⚪"
with st.expander(f"{icon} {hit.get('note_id', '?')} ({score:.2f})"):
st.markdown(f"_{hit.get('source', {}).get('text', '')[:300]}..._")
if hit.get('explanation'):
st.caption(f"Grund: {hit['explanation']['reasons'][0]['message']}")
# Granular Feedback (Faces)
def _cb(qid=msg["query_id"], nid=hit['node_id']):
val = st.session_state.get(f"fb_src_{qid}_{nid}")
if val is not None: submit_feedback(qid, nid, val+1, "Faces UI")
st.feedback("faces", key=f"fb_src_{msg['query_id']}_{hit['node_id']}", on_change=_cb)
# Global Feedback (Stars)
qid = msg["query_id"]
st.feedback("stars", key=f"fb_glob_{qid}", on_change=lambda: submit_feedback(qid, "generated_answer", st.session_state[f"fb_glob_{qid}"]+1))
else:
st.markdown(msg["content"])
# Input Logic
last_msg_is_user = len(st.session_state.messages) > 0 and st.session_state.messages[-1]["role"] == "user"
if prompt := st.chat_input("Frage Mindnet..."):
st.session_state.messages.append({"role": "user", "content": prompt})
st.rerun()
if last_msg_is_user:
last_prompt = st.session_state.messages[-1]["content"]
with st.chat_message("assistant"):
with st.spinner("Thinking..."):
resp = send_chat_message(last_prompt, top_k, explain)
if "error" in resp:
st.error(resp["error"])
else:
msg_data = {
"role": "assistant",
"content": resp.get("answer"),
"intent": resp.get("intent", "FACT"),
"intent_source": resp.get("intent_source", "Unknown"), # Wichtig für Anzeige
"sources": resp.get("sources", []),
"query_id": resp.get("query_id")
}
st.session_state.messages.append(msg_data)
st.rerun()
def render_creation_interface():
st.header("📝 Neuer Wissens-Eintrag (WP-07/11)")
st.info("Hier kannst du strukturierte Notizen erstellen, die direkt in den Obsidian Vault gespeichert werden.")
with st.form("new_entry"):
col1, col2 = st.columns([3, 1])
title = col1.text_input("Titel der Notiz", placeholder="z.B. Projekt Gamma Meeting")
n_type = col2.selectbox("Typ", ["concept", "meeting", "person", "project", "decision"])
content = st.text_area("Inhalt (Markdown)", height=300, placeholder="# Protokoll\n\n- Punkt 1...")
st.markdown("**Automatische Vernetzung:**")
st.caption("Verwende `[[Link]]` für Referenzen und `[[rel:depends_on X]]` für logische Kanten.")
submitted = st.form_submit_button("💾 Speichern & Indizieren")
if submitted:
st.success(f"Mockup: Notiz '{title}' ({n_type}) wäre jetzt gespeichert worden!")
st.balloons()
# --- MAIN LOOP ---
mode, top_k, explain = render_sidebar()
if mode == "💬 Chat":
render_chat_interface(top_k, explain)
else:
render_creation_interface()
+14 -7
View File
@@ -3,12 +3,12 @@ app/models/dto.py — Pydantic-Modelle (DTOs) für WP-04/WP-05/WP-06
Zweck:
Laufzeit-Modelle für FastAPI (Requests/Responses).
WP-06 Update: Intent in ChatResponse.
WP-06 Update: Intent & Intent-Source in ChatResponse.
Version:
0.6.0 (WP-06: Decision Engine)
0.6.2 (WP-06: Decision Engine Transparency, Erweiterung des Feeback Request)
Stand:
2025-12-08
2025-12-09
"""
from __future__ import annotations
@@ -64,11 +64,14 @@ class QueryRequest(BaseModel):
class FeedbackRequest(BaseModel):
"""
User-Feedback zu einem spezifischen Treffer.
User-Feedback zu einem spezifischen Treffer oder der Gesamtantwort.
"""
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)")
# node_id ist optional: Wenn leer oder "generated_answer", gilt es für die Antwort.
# Wenn eine echte Chunk-ID, gilt es für die Quelle.
node_id: str = Field(..., description="ID des bewerteten Treffers oder 'generated_answer'")
# Update: Range auf 1-5 erweitert für differenziertes Tuning
score: int = Field(..., ge=1, le=5, description="1 (Irrelevant/Falsch) bis 5 (Perfekt)")
comment: Optional[str] = None
@@ -123,6 +126,7 @@ class QueryHit(BaseModel):
total_score: float
paths: Optional[List[List[Dict]]] = None
source: Optional[Dict] = None
payload: Optional[Dict] = None # Added for flexibility & WP-06 meta-data
explanation: Optional[Explanation] = None
@@ -150,4 +154,7 @@ class ChatResponse(BaseModel):
answer: str = Field(..., description="Generierte Antwort vom LLM")
sources: List[QueryHit] = Field(..., description="Die für die Antwort genutzten Quellen")
latency_ms: int
intent: Optional[str] = Field("FACT", description="WP-06: Erkannter Intent (FACT/DECISION)")
intent: Optional[str] = Field("FACT", description="WP-06: Erkannter Intent (FACT/DECISION)")
intent_source: Optional[str] = Field("Unknown", description="WP-06: Quelle der Intent-Erkennung (Keyword vs. LLM)")
+50 -32
View File
@@ -1,6 +1,12 @@
"""
app/routers/chat.py — RAG Endpunkt (WP-06 Hybrid Router v2)
Update: Robusteres LLM-Parsing für Small Language Models (SLMs).
app/routers/chat.py — RAG Endpunkt (WP-06 Hybrid Router + WP-04c Feedback)
Version: 2.3.2 (Merged Stability Patch)
Features:
- Hybrid Intent Router (Keyword + LLM)
- Strategic Retrieval (Late Binding via Config)
- Context Enrichment (Payload/Source Fallback)
- Data Flywheel (Feedback Logging Integration)
"""
from fastapi import APIRouter, HTTPException, Depends
@@ -15,6 +21,8 @@ from app.config import get_settings
from app.models.dto import ChatRequest, ChatResponse, QueryRequest, QueryHit
from app.services.llm_service import LLMService
from app.core.retriever import Retriever
# [MERGE] Integration Feedback Service (WP-04c)
from app.services.feedback_service import log_search
router = APIRouter()
logger = logging.getLogger(__name__)
@@ -76,7 +84,11 @@ def _build_enriched_context(hits: List[QueryHit]) -> str:
"[Kein Text]"
)
title = hit.note_id or "Unbekannt"
note_type = source.get("type", "unknown").upper()
# [FIX] Robustes Auslesen des Typs (Payload > Source > Unknown)
payload = hit.payload or {}
note_type = payload.get("type") or source.get("type", "unknown")
note_type = str(note_type).upper()
entry = (
f"### QUELLE {i}: {title}\n"
@@ -87,11 +99,10 @@ def _build_enriched_context(hits: List[QueryHit]) -> str:
return "\n\n".join(context_parts)
async def _classify_intent(query: str, llm: LLMService) -> str:
async def _classify_intent(query: str, llm: LLMService) -> tuple[str, str]:
"""
Hybrid Router v2:
1. Keyword Check (Best/Longest Match) -> FAST
2. LLM Fallback (Robust Parsing) -> SMART
Hybrid Router v3:
Gibt Tuple zurück: (Intent, Source)
"""
config = get_full_config()
strategies = config.get("strategies", {})
@@ -112,8 +123,7 @@ async def _classify_intent(query: str, llm: LLMService) -> str:
best_intent = intent_name
if best_intent:
logger.info(f"Intent detected via KEYWORD: {best_intent}")
return best_intent
return best_intent, "Keyword (Fast Path)"
# 2. SLOW PATH: LLM Router
if settings.get("llm_fallback_enabled", False):
@@ -122,35 +132,23 @@ async def _classify_intent(query: str, llm: LLMService) -> str:
prompt = router_prompt_template.replace("{query}", query)
logger.info("Keywords failed. Asking LLM for Intent...")
# Kurzer Raw Call
raw_response = await llm.generate_raw_response(prompt)
# --- Robust Parsing für SLMs ---
# Wir suchen nach den bekannten Strategie-Namen im Output
# Parsing logic
llm_output_upper = raw_response.upper()
logger.info(f"LLM Router Raw Output: '{raw_response}'") # Debugging
found_intents = []
for strat_key in strategies.keys():
# Wir prüfen, ob der Strategie-Name (z.B. "EMPATHY") im Text vorkommt
if strat_key in llm_output_upper:
found_intents.append(strat_key)
# Entscheidung
final_intent = "FACT"
if len(found_intents) == 1:
# Eindeutiger Treffer
final_intent = found_intents[0]
logger.info(f"Intent detected via LLM (Parsed): {final_intent}")
return final_intent
return found_intents[0], "LLM Router (Slow Path)"
elif len(found_intents) > 1:
# Mehrere Treffer (z.B. "Es ist FACT oder DECISION") -> Nimm den ersten oder Fallback
logger.warning(f"LLM returned multiple intents {found_intents}. Using first match: {found_intents[0]}")
return found_intents[0]
return found_intents[0], f"LLM Ambiguous {found_intents}"
else:
logger.warning(f"LLM did not return a valid strategy name. Falling back to FACT.")
return "FACT", "LLM Fallback (No Match)"
return "FACT"
return "FACT", "Default (No Match)"
@router.post("/", response_model=ChatResponse)
async def chat_endpoint(
@@ -163,9 +161,9 @@ async def chat_endpoint(
logger.info(f"Chat request [{query_id}]: {request.message[:50]}...")
try:
# 1. Intent Detection
intent = await _classify_intent(request.message, llm)
logger.info(f"[{query_id}] Final Intent: {intent}")
# 1. Intent Detection (mit Source)
intent, intent_source = await _classify_intent(request.message, llm)
logger.info(f"[{query_id}] Final Intent: {intent} via {intent_source}")
# Strategy Load
strategy = get_decision_strategy(intent)
@@ -183,7 +181,7 @@ async def chat_endpoint(
retrieve_result = await retriever.search(query_req)
hits = retrieve_result.results
# 3. Strategic Retrieval
# 3. Strategic Retrieval (WP-06 Kernfeature)
if inject_types:
logger.info(f"[{query_id}] Executing Strategic Retrieval for types: {inject_types}...")
strategy_req = QueryRequest(
@@ -217,17 +215,37 @@ async def chat_endpoint(
logger.info(f"[{query_id}] Sending to LLM (Intent: {intent}, Template: {prompt_key})...")
# System-Prompt separat übergeben
# System-Prompt separat übergeben (WP-06a Fix)
answer_text = await llm.generate_raw_response(prompt=final_prompt, system=system_prompt)
duration_ms = int((time.time() - start_time) * 1000)
# 6. Logging (Fire & Forget) - [MERGE POINT]
# Wir loggen alles für das Data Flywheel (WP-08 Self-Tuning)
try:
log_search(
query_id=query_id,
query_text=request.message,
results=hits,
mode="chat_rag",
metadata={
"intent": intent,
"intent_source": intent_source,
"generated_answer": answer_text,
"model": llm.settings.LLM_MODEL
}
)
except Exception as e:
logger.error(f"Logging failed: {e}")
# 7. Response
return ChatResponse(
query_id=query_id,
answer=answer_text,
sources=hits,
latency_ms=duration_ms,
intent=intent
intent=intent,
intent_source=intent_source
)
except Exception as e:
+44 -26
View File
@@ -2,13 +2,18 @@
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).
Version: 1.1 (Chat-Support)
"""
import json
import os
import time
import logging
from pathlib import Path
from typing import Dict, Any, List
from app.models.dto import QueryRequest, QueryResponse, FeedbackRequest
from typing import Dict, Any, List, Union
from app.models.dto import QueryRequest, QueryResponse, FeedbackRequest, QueryHit
logger = logging.getLogger(__name__)
# Pfad für Logs (lokal auf dem Beelink/PC)
LOG_DIR = Path("data/logs")
@@ -19,18 +24,35 @@ def _ensure_log_dir():
if not LOG_DIR.exists():
os.makedirs(LOG_DIR, exist_ok=True)
def log_search(req: QueryRequest, res: QueryResponse):
def _append_jsonl(file_path: Path, data: dict):
try:
with open(file_path, "a", encoding="utf-8") as f:
f.write(json.dumps(data, ensure_ascii=False) + "\n")
except Exception as e:
logger.error(f"Failed to write log: {e}")
def log_search(
query_id: str,
query_text: str,
results: List[QueryHit],
mode: str = "unknown",
metadata: Dict[str, Any] = None
):
"""
Speichert den "Snapshot" der Suche.
WICHTIG: Wir speichern die Scores (Breakdown), damit wir später wissen,
warum das System so entschieden hat.
Generische Logging-Funktion für Suche UND Chat.
Args:
query_id: UUID der Anfrage.
query_text: User-Eingabe.
results: Liste der Treffer (QueryHit Objekte).
mode: z.B. "semantic", "hybrid", "chat_rag".
metadata: Zusätzliche Infos (z.B. generierte Antwort, Intent).
"""
_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
for hit in results:
# Pydantic Model Dump für saubere Serialisierung
breakdown = None
if hit.explanation and hit.explanation.breakdown:
breakdown = hit.explanation.breakdown.model_dump()
@@ -39,25 +61,24 @@ def log_search(req: QueryRequest, res: QueryResponse):
"node_id": hit.node_id,
"note_id": hit.note_id,
"total_score": hit.total_score,
"breakdown": breakdown, # Wichtig für Training!
"breakdown": breakdown,
"rank_semantic": hit.semantic_score,
"rank_edge": hit.edge_bonus
"rank_edge": hit.edge_bonus,
"type": hit.source.get("type") if hit.source else "unknown"
})
entry = {
"timestamp": time.time(),
"query_id": res.query_id,
"query_text": req.query,
"mode": req.mode,
"top_k": req.top_k,
"hits": hits_summary
"query_id": query_id,
"query_text": query_text,
"mode": mode,
"hits_count": len(hits_summary),
"hits": hits_summary,
"metadata": metadata or {}
}
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}")
_append_jsonl(SEARCH_LOG_FILE, entry)
logger.info(f"Logged search/chat interaction {query_id}")
def log_feedback(fb: FeedbackRequest):
"""
@@ -73,8 +94,5 @@ def log_feedback(fb: FeedbackRequest):
"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}")
_append_jsonl(FEEDBACK_LOG_FILE, entry)
logger.info(f"Logged feedback for {fb.query_id}")
+8 -2
View File
@@ -1,7 +1,7 @@
# mindnet v2.2 – Knowledge Design Manual
**Datei:** `docs/mindnet_knowledge_design_manual_v2.2.md`
**Stand:** 2025-12-09
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
**Stand:** 2025-12-10
**Status:** **FINAL** (Integrierter Stand WP01–WP10)
**Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_functional_architecture.md`.
---
@@ -27,6 +27,7 @@ Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das dein
Seit Version 2.3.1 verfügt Mindnet über:
* **Hybrid Router:** Das System erkennt, ob du Fakten, Entscheidungen oder Empathie brauchst.
* **Context Intelligence:** Das System lädt je nach Situation unterschiedliche Notiz-Typen (z.B. Werte bei Entscheidungen).
* **Web UI (WP10):** Du kannst direkt sehen, welche Quellen genutzt wurden.
### 1.2 Der Vault als „Source of Truth“
Die Markdown-Dateien in deinem Vault sind die **einzige Quelle der Wahrheit**.
@@ -194,6 +195,11 @@ Erstelle Notizen mit `type: experience`. Nutze im Text **emotionale Brückenwör
*Effekt:* Wenn du im Chat jammerst ("Alles ist sinnlos"), findet das System diese Notiz und spiegelt dir deine eigene Erfahrung zurück.
### 5.3 Schreiben für den Chat (UI Optimization)
Da deine Notizen im Web-Interface (WP10) angezeigt werden:
* **Kurze Absätze:** Das LLM liest besser, und der Mensch scannt schneller.
* **Klare Headings:** Nutze H1/H2, um dem Chunker logische Trennlinien zu geben.
---
## 6. Best Practices & Beispiele (Klassik)
+7 -6
View File
@@ -1,7 +1,7 @@
# Mindnet v2.2 – Overview & Einstieg
**Datei:** `docs/mindnet_overview_v2.2.md`
**Stand:** 2025-12-09
**Status:** **FINAL** (Post-WP06 Release)
**Stand:** 2025-12-10
**Status:** **FINAL** (Post-WP10 Release)
**Version:** 2.3.1
---
@@ -39,7 +39,8 @@ Mindnet arbeitet auf drei Schichten, die aufeinander aufbauen:
### Ebene 3: Identität (Die Persönlichkeit)
* **Funktion:** Interaktion und Bewertung. Das System nimmt eine Haltung ein.
* **Logik:** "Ich empfehle Lösung X, weil sie unserem Wert 'Datensparsamkeit' entspricht."
* **Technik:** * **Intent Router:** Erkennt Absichten (Fakt vs. Gefühl vs. Entscheidung).
* **Technik:**
* **Intent Router:** Erkennt Absichten (Fakt vs. Gefühl vs. Entscheidung).
* **Strategic Retrieval:** Lädt gezielt Werte oder Erfahrungen nach.
* **Multi-Persona:** Passt den Tonfall an.
* **Status:** 🟢 Live (WP05–WP06).
@@ -61,7 +62,7 @@ Der Datenfluss in Mindnet ist zyklisch ("Data Flywheel"):
* **Backend:** Python 3.12, FastAPI.
* **Datenbank:** Qdrant (Vektor & Graph).
* **KI:** Ollama (Phi-3 Mini / Mistral) – 100% lokal.
* **Frontend:** Terminal (aktuell) / Web-UI (geplant WP10).
* **Frontend:** Streamlit Web-UI (v2.3.1).
---
@@ -91,5 +92,5 @@ Wo findest du was?
## 6. Aktueller Fokus
Wir haben **Phase C (Persönlichkeit)** mit WP06 (Decision Engine) abgeschlossen.
Das System kann nun strategisch denken und fühlen. Als Nächstes folgt **Phase D (Interaktion)** mit dem **Chat Interface (WP10)** für bessere Usability.
Wir haben **Phase D (Interaktion)** mit WP10 (Chat Interface) begonnen und die UI erfolgreich deployed.
Das System ist nun für Endnutzer bedienbar. Als Nächstes folgt der **Interview-Assistent (WP07)**, um Wissen dialogisch zu erfassen.
+76 -42
View File
@@ -1,19 +1,19 @@
# Mindnet v2.2 – Admin Guide
**Datei:** `docs/mindnet_admin_guide_v2.2.md`
**Stand:** 2025-12-09
**Status:** **FINAL** (Inkl. RAG, Decision Engine & LLM Ops)
**Stand:** 2025-12-10
**Status:** **FINAL** (Inkl. Frontend Deployment)
**Quellen:** `Handbuch.md`, `mindnet_developer_guide_v2.2.md`.
> Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + DB + LLM).
> Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + UI + DB).
---
## 1. Zielgruppe & Scope
Mindnet ist als **Single-Node System** konzipiert, das lokal (z.B. Laptop) oder auf einem privaten Server (Homelab, Intranet) läuft.
Mindnet ist als **Multi-Service-Architektur** konzipiert, die lokal oder auf einem privaten Server läuft.
Wir unterscheiden strikt zwischen:
* **Production (Port 8001):** Stabiler `main` Branch.
* **Development (Port 8002):** Experimentelle Feature-Branches.
* **Production:** Backend (8001) + Frontend (8501). Stabiler `main` Branch.
* **Development:** Backend (8002) + Frontend (8502). Experimentelle Feature-Branches.
---
@@ -36,9 +36,11 @@ Wir unterscheiden strikt zwischen:
# 2. Umgebung einrichten
python3 -m venv .venv
source .venv/bin/activate
# 3. Dependencies installieren (inkl. Streamlit)
pip install -r requirements.txt
# 3. Verzeichnisse anlegen
# 4. Verzeichnisse anlegen
mkdir -p logs qdrant_storage data/logs
### 2.3 Qdrant Setup (Docker)
@@ -55,7 +57,7 @@ Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig.
Mindnet benötigt einen lokalen LLM-Server für den Chat.
# 1. Installieren (Linux Script)
curl -fsSL https://ollama.com/install.sh | sh
curl -fsSL [https://ollama.com/install.sh](https://ollama.com/install.sh) | sh
# 2. Modell laden (Phi-3 Mini für CPU-Performance)
ollama pull phi3:mini
@@ -75,24 +77,64 @@ Erstelle eine `.env` Datei im Root-Verzeichnis. Die neuen Settings für WP-06 (T
# LLM / RAG Settings
MINDNET_LLM_MODEL="phi3:mini"
MINDNET_OLLAMA_URL="http://127.0.0.1:11434"
MINDNET_OLLAMA_URL="[http://127.0.0.1:11434](http://127.0.0.1:11434)"
# NEU in v2.3: Config & Timeouts
# Pfad zu Prompts
# Config & Timeouts
MINDNET_PROMPTS_PATH="./config/prompts.yaml"
# Pfad zur Decision Engine Config
MINDNET_DECISION_CONFIG="./config/decision_engine.yaml"
# Timeout in Sekunden (300s = 5min fuer Cold Starts)
MINDNET_LLM_TIMEOUT=300.0
### 2.6 Deployment via Systemd
Mindnet wird als Systemdienst gestartet. Ollama läuft meist als eigener Dienst (`ollama.service`).
### 2.6 Deployment via Systemd (Backend & Frontend)
**Production Service (`/etc/systemd/system/mindnet-prod.service`):**
* Läuft auf Port 8001.
* Autostart (`enabled`).
* Restart Policy: `always`.
* Abhängigkeit: Sollte nach `docker` und `ollama` starten.
Mindnet benötigt zwei Services pro Umgebung: API (Uvicorn) und UI (Streamlit).
**Production Backend (`/etc/systemd/system/mindnet-prod.service`):**
[Unit]
Description=Mindnet API Prod (8001)
After=network.target
[Service]
User=llmadmin
Group=llmadmin
WorkingDirectory=/home/llmadmin/mindnet
ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
**Production Frontend (`/etc/systemd/system/mindnet-ui-prod.service`):**
[Unit]
Description=Mindnet UI Prod (8501)
After=mindnet-prod.service
[Service]
User=llmadmin
Group=llmadmin
WorkingDirectory=/home/llmadmin/mindnet
# Environment Variables
Environment="MINDNET_API_URL=http://localhost:8001"
Environment="MINDNET_API_TIMEOUT=300"
Environment="STREAMLIT_SERVER_PORT=8501"
Environment="STREAMLIT_SERVER_ADDRESS=0.0.0.0"
Environment="STREAMLIT_SERVER_HEADLESS=true"
ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
**Firewall (UFW):**
Öffne die Ports für den Zugriff:
sudo ufw allow 8501/tcp # Prod UI
sudo ufw allow 8502/tcp # Dev UI (falls gewünscht)
---
@@ -106,27 +148,19 @@ Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant
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
### 3.2 Health-Checks
Prüfe regelmäßig, ob alle drei Komponenten (API, DB, LLM) laufen.
**Status prüfen:**
Prüfe regelmäßig, ob alle Komponenten laufen.
sudo systemctl status mindnet-prod
sudo systemctl status mindnet-ui-prod
sudo systemctl status ollama
**Logischer Smoke-Test:**
python3 scripts/test_retriever_smoke.py --mode hybrid --url http://localhost:8001/query
### 3.3 Logs & Monitoring
* **Technische Fehler (API):** `journalctl -u mindnet-prod -f`
* Achte auf: `LLM Router Raw Output`. Hier siehst du, wie die Decision Engine entscheidet.
* **LLM Fehler (Ollama):** `journalctl -u ollama -f`
* **Backend Fehler:** `journalctl -u mindnet-prod -f`
* **Frontend Fehler:** `journalctl -u mindnet-ui-prod -f`
* Achte auf "Timeout"-Meldungen im Frontend, wenn das Backend zu langsam antwortet.
* **LLM Fehler:** `journalctl -u ollama -f`
* **Fachliche Logs:** `data/logs/search_history.jsonl`
**Troubleshooting Chat:**
* Wenn `/chat` in den Timeout läuft (>300s): Prüfe `MINDNET_LLM_TIMEOUT` in `.env` und ob das Modell im RAM liegt.
* Wenn `/chat` halluziniert: Prüfe `config/prompts.yaml` und ob der Import aktuell ist.
---
## 4. Update-Prozess
@@ -143,9 +177,10 @@ Wenn neue Versionen ausgerollt werden (Deployment):
source .venv/bin/activate
pip install -r requirements.txt
3. **Dienst neustarten (Zwingend!):**
3. **Dienste neustarten (Zwingend!):**
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod
4. **Schema-Migration (falls nötig):**
@@ -158,7 +193,7 @@ Wenn neue Versionen ausgerollt werden (Deployment):
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 (Git/NAS).
Der Markdown-Vault ist die **Single Source of Truth**.
### 5.2 Qdrant-Snapshots (Priorität 2)
Für schnelle Wiederherstellung des Suchindex.
@@ -168,7 +203,7 @@ Für schnelle Wiederherstellung des Suchindex.
docker start mindnet_qdrant
### 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.
Sichere den Ordner `data/logs/`. Verlust dieser Daten bedeutet Verlust des Trainingsmaterials für Self-Tuning.
### 5.4 Notfall-Wiederherstellung (Rebuild)
Wenn die Datenbank korrupt ist:
@@ -184,10 +219,9 @@ Wenn die Datenbank korrupt ist:
### 6.1 Zugriffsschutz
Mindnet hat aktuell **keine integrierte Authentifizierung**.
* **API:** Muss hinter einem Reverse Proxy (Nginx) mit Basic Auth laufen.
* **Qdrant:** Sollte via Firewall (ufw) auf `127.0.0.1` beschränkt sein.
* **Ollama:** Standardmäßig hört Ollama nur auf `localhost`. Das ist sicher.
* **Frontend:** Streamlit auf Port 8501 ist offen. Nutze Nginx Basic Auth oder VPN.
* **API:** Sollte nicht direkt im öffentlichen Netz stehen.
* **Qdrant:** Auf `127.0.0.1` beschränken.
### 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.
Änderungen an der `types.yaml` (z.B. neue Gewichte) wirken global und erfordern Tests.
+7 -4
View File
@@ -1,7 +1,7 @@
# Mindnet v2.2 – Appendices & Referenzen
**Datei:** `docs/mindnet_appendices_v2.2.md`
**Stand:** 2025-12-09
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
**Stand:** 2025-12-10
**Status:** **FINAL** (Integrierter Stand WP01–WP10)
**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.
@@ -71,6 +71,7 @@ Diese sind die Felder, die effektiv in Qdrant gespeichert werden.
{
"chunk_id": "string (keyword)", // Format: {note_id}#c{index}
"note_id": "string (keyword)", // FK zur Note
"type": "string (keyword)", // Typ-Kopie aus Note (Neu in WP06a)
"text": "string (text)", // Reintext für Anzeige (ohne Overlap)
"window": "string (text)", // Text + Overlap (für Embedding)
"ord": "integer", // Laufende Nummer (1..N)
@@ -127,7 +128,7 @@ Diese Variablen steuern das Verhalten der Skripte und Container.
---
## Anhang F: Workpackage Status (v2.3.1)
## Anhang F: Workpackage Status (v2.3.2)
Aktueller Implementierungsstand der Module.
@@ -141,5 +142,7 @@ Aktueller Implementierungsstand der Module.
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Chat mit Context Enrichment. |
| **WP06** | Decision Engine | 🟢 Live | Hybrid Router, Strategic Retrieval, Multi-Persona. |
| **WP07** | Interview Assistent | 🟡 Geplant | Dialog-Modus (Nächster Schritt). |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
| **WP10** | Chat Interface | 🟡 Geplant | Nächster Schritt (Frontend). |
| **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). |
| **WP10a**| GUI Evolution | 🔴 Geplant | Interaktive Tools & Editor. |
+41 -22
View File
@@ -1,6 +1,6 @@
# Mindnet v2.2 – Entwickler-Workflow
**Datei:** `DEV_WORKFLOW.md`
**Stand:** 2025-12-09 (Aktualisiert: LLM Timeouts & Systemd)
**Stand:** 2025-12-10 (Aktualisiert: Inkl. Frontend WP10)
Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
@@ -11,8 +11,12 @@ Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE),
* **Windows 11 (VS Code):** Hier schreibst du Code. **Nie** direkt auf `main` arbeiten!
* **Raspberry Pi (Gitea):** Der Tresor. Speichert den Code und verwaltet Versionen.
* **Beelink (Runtime):** Hier läuft die Software. Wir nutzen **Systemd-Services**:
* **PROD (`mindnet-prod`):** Läuft stabil auf `main`. Ordner: `~/mindnet`. **Port 8001**.
* **DEV (`mindnet-dev`):** Deine Spielwiese. Ordner: `~/mindnet_dev`. **Port 8002**.
* **PROD:**
* API: `mindnet-prod` (Port 8001). Ordner: `~/mindnet`.
* UI: `mindnet-ui-prod` (Port 8501).
* **DEV:**
* API: `mindnet-dev` (Port 8002). Ordner: `~/mindnet_dev`.
* UI: `mindnet-ui-dev` (Port 8502).
---
@@ -71,45 +75,53 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.
```
5. **Test-Server aktualisieren (WICHTIG):**
Der Code ist da, aber der Prozess im RAM ist noch alt. Wir müssen den Service neustarten.
Der Code ist da, aber die Prozesse im RAM sind noch alt. Wir müssen die Services neustarten.
**Option A: Standard (Als Service laufen lassen)**
Ideal, wenn du nur testen willst, ob es läuft.
```bash
# 1. API neustarten
sudo systemctl restart mindnet-dev
# 2. UI neustarten (falls Frontend-Änderungen)
sudo systemctl restart mindnet-ui-dev
# Logs prüfen (um Fehler zu sehen):
journalctl -u mindnet-dev -f
# Oder Frontend Logs:
journalctl -u mindnet-ui-dev -f
```
**Option B: Manuell Debuggen (Direct Output)**
Ideal, wenn du Print-Ausgaben direkt sehen willst oder der Service dauernd crasht.
```bash
# 1. Service stoppen (wichtig, sonst ist Port 8002 belegt!)
# 1. Services stoppen (wichtig, sonst sind Ports 8002/8502 belegt!)
sudo systemctl stop mindnet-dev
sudo systemctl stop mindnet-ui-dev
# 2. Manuell starten
# 2. Manuell starten (z.B. API)
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
# ... Testen ...
# 3. Wenn fertig: Service wieder anschalten (Optional)
# 3. Wenn fertig: Services wieder anschalten (Optional)
# Strg+C drücken
sudo systemctl start mindnet-dev
sudo systemctl start mindnet-ui-dev
```
6. **Validieren:**
Führe deine Tests in einem **zweiten Terminal** aus:
```bash
# Beispiel für Decision Engine Test
python tests/test_wp06_decision.py -p 8002 -q "Soll ich...?"
```
* **Browser:** Öffne `http://<IP>:8502` um die UI zu testen.
* **CLI:** Führe Testskripte in einem **zweiten Terminal** aus:
```bash
# Beispiel für Decision Engine Test
python tests/test_wp06_decision.py -p 8002 -q "Soll ich...?"
```
---
### Phase 3: Release (Gitea / Raspberry Pi)
Wenn der Test auf Port 8002 erfolgreich war:
Wenn der Test auf Port 8002 / 8502 erfolgreich war:
1. Öffne Gitea im Browser.
2. Erstelle einen **Pull Request** (Dein Branch -> `main`).
@@ -119,7 +131,7 @@ Wenn der Test auf Port 8002 erfolgreich war:
### Phase 4: Deployment (Beelink / `mindnet`)
Jetzt bringen wir die Änderung in das Live-System (Port 8001).
Jetzt bringen wir die Änderung in das Live-System (Port 8001 / 8501).
1. **Deploy-Agent (Automatisch):**
Wenn dein `deploy.yml` aktiv ist, passiert das jetzt von selbst!
@@ -129,8 +141,13 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001).
cd /home/llmadmin/mindnet
git pull origin main
# Produktions-Service neustarten
# Dependencies updaten
source .venv/bin/activate
pip install -r requirements.txt
# Produktions-Services neustarten
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod
# Kurz prüfen, ob er läuft
sudo systemctl status mindnet-prod
@@ -163,8 +180,10 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
| :--- | :--- | :--- |
| **VS Code** | `Sync (auf main)` | **WICHTIG:** Holt neuesten Code vom Server. |
| **Beelink** | `git fetch` | Aktualisiert Liste der Remote-Branches. |
| **Beelink** | `sudo systemctl restart mindnet-dev` | **Neustart Dev-Server (Port 8002).** |
| **Beelink** | `journalctl -u mindnet-dev -f` | **Live-Logs vom Dev-Server sehen.** |
| **Beelink** | `sudo systemctl restart mindnet-dev` | **Neustart Dev-Backend (Port 8002).** |
| **Beelink** | `sudo systemctl restart mindnet-ui-dev` | **Neustart Dev-Frontend (Port 8502).** |
| **Beelink** | `journalctl -u mindnet-dev -f` | **Live-Logs Backend.** |
| **Beelink** | `journalctl -u mindnet-ui-dev -f` | **Live-Logs Frontend.** |
---
@@ -173,13 +192,13 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
**"Read timed out (120s)" / 500 Error beim Chat**
* **Ursache:** Das LLM (Ollama) braucht zu lange zum Laden ("Cold Start").
* **Lösung:**
1. Erhöhe in `.env` den Wert: `MINDNET_LLM_TIMEOUT=300.0`.
2. Starte den Server neu (`sudo systemctl restart mindnet-dev`).
1. Erhöhe in `.env` den Wert: `MINDNET_LLM_TIMEOUT=300.0` (Backend) oder `MINDNET_API_TIMEOUT` (Frontend).
2. Starte die Server neu.
3. Stelle sicher, dass dein Test-Skript (Client) auch ein hohes Timeout hat.
**"Port 8002 already in use"**
* **Ursache:** Du willst `uvicorn` manuell starten, aber der Service läuft noch.
* **Lösung:** `sudo systemctl stop mindnet-dev`.
**"Port 8002 / 8502 already in use"**
* **Ursache:** Du willst `uvicorn` oder `streamlit` manuell starten, aber der Service läuft noch.
* **Lösung:** `sudo systemctl stop mindnet-dev` bzw. `mindnet-ui-dev`.
**"UnicodeDecodeError in .env"**
* **Ursache:** Umlaute oder Sonderzeichen in der `.env` Datei.
+40 -32
View File
@@ -1,7 +1,7 @@
# Mindnet v2.2 – Developer Guide
**Datei:** `docs/mindnet_developer_guide_v2.2.md`
**Stand:** 2025-12-09
**Status:** **FINAL** (Inkl. RAG, Decision Engine & AI-Teaching)
**Stand:** 2025-12-10
**Status:** **FINAL** (Inkl. RAG, Decision Engine & Frontend WP10)
**Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`.
> **Zielgruppe:** Entwickler:innen.
@@ -9,16 +9,17 @@
---
- [Mindnet v2.2 – Developer Guide](#mindnet-v22--developer-guide)
- [1. Projektstruktur (Post-WP06)](#1-projektstruktur-post-wp06)
- [1. Projektstruktur (Post-WP10)](#1-projektstruktur-post-wp10)
- [2. Lokales Setup (Development)](#2-lokales-setup-development)
- [2.1 Voraussetzungen](#21-voraussetzungen)
- [2.2 Installation](#22-installation)
- [2.3 Konfiguration (Environment)](#23-konfiguration-environment)
- [2.4 Dienste starten (Systemd bevorzugt)](#24-dienste-starten-systemd-bevorzugt)
- [2.4 Dienste starten (API \& UI)](#24-dienste-starten-api--ui)
- [3. Core-Module \& Entwicklung](#3-core-module--entwicklung)
- [3.1 Der Importer (`scripts.import_markdown`)](#31-der-importer-scriptsimport_markdown)
- [3.2 Der Hybrid Router (`app.routers.chat`)](#32-der-hybrid-router-approuterschat)
- [3.3 Der Retriever (`app.core.retriever`)](#33-der-retriever-appcoreretriever)
- [3.4 Das Frontend (`app.frontend.ui`)](#34-das-frontend-appfrontendui)
- [4. Tests \& Debugging](#4-tests--debugging)
- [4.1 Unit Tests (Pytest)](#41-unit-tests-pytest)
- [4.2 Integration / Pipeline Tests](#42-integration--pipeline-tests)
@@ -31,7 +32,7 @@
---
## 1. Projektstruktur (Post-WP06)
## 1. Projektstruktur (Post-WP10)
Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt.
@@ -54,6 +55,8 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
│ │ ├── llm_service.py # Ollama Client (Mit Timeout & Raw-Mode)
│ │ ├── feedback_service.py # Logging (JSONL Writer)
│ │ └── embeddings_client.py
│ ├── frontend/ # NEU (WP10)
│ │ └── ui.py # Streamlit Application
│ └── main.py # Entrypoint der API
├── config/ # YAML-Konfigurationen (Single Source of Truth)
│ ├── types.yaml # Import-Regeln
@@ -86,7 +89,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
python3 -m venv .venv
source .venv/bin/activate
# 3. Abhängigkeiten installieren
# 3. Abhängigkeiten installieren (inkl. Streamlit)
pip install -r requirements.txt
# 4. Ollama Setup (Modell laden)
@@ -94,7 +97,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
ollama pull phi3:mini
### 2.3 Konfiguration (Environment)
Erstelle eine `.env` Datei im Root-Verzeichnis. Die Timeout-Settings sind kritisch für CPU-Inference.
Erstelle eine `.env` Datei im Root-Verzeichnis.
# Qdrant Verbindung
QDRANT_URL="http://localhost:6333"
@@ -112,28 +115,28 @@ Erstelle eine `.env` Datei im Root-Verzeichnis. Die Timeout-Settings sind kritis
MINDNET_PROMPTS_PATH="./config/prompts.yaml"
MINDNET_DECISION_CONFIG="./config/decision_engine.yaml"
# Frontend Settings (WP10)
MINDNET_API_URL="http://localhost:8002"
# Import-Strategie
MINDNET_HASH_COMPARE="Body"
MINDNET_HASH_SOURCE="parsed"
### 2.4 Dienste starten (Systemd bevorzugt)
Auf dem Entwicklungsserver (Beelink) nutzen wir Systemd.
### 2.4 Dienste starten (API & UI)
# Starten / Neustarten
sudo systemctl restart mindnet-dev
# Logs prüfen (Wichtig für LLM Debugging)
journalctl -u mindnet-dev -f
Wir entwickeln mit zwei Services. Du kannst sie manuell in zwei Terminals starten oder die Systemd-Services nutzen (siehe `admin_guide.md`).
Falls du lokal auf Windows entwickelst:
**Terminal A: Backend (API)**
# 1. Qdrant starten
docker run -p 6333:6333 qdrant/qdrant
# 2. Ollama starten
ollama serve
# 3. API starten
# Startet auf Port 8002 (Dev Standard)
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env --reload
**Terminal B: Frontend (UI)**
# Startet auf Port 8502 (Dev Standard)
# --server.port 8502 verhindert Konflikte mit Prod (8501)
streamlit run app/frontend/ui.py --server.port 8502
---
## 3. Core-Module & Entwicklung
@@ -155,6 +158,12 @@ Hier passiert das Scoring.
* **Hybrid Search:** Der Chat-Endpoint erzwingt `mode="hybrid"`.
* **Strategic Retrieval:** In `chat.py` wird der Retriever *zweimal* aufgerufen, wenn ein Intent (z.B. `DECISION`) eine Injection (`value`) erfordert.
### 3.4 Das Frontend (`app.frontend.ui`)
Eine Streamlit-App (WP10).
* **State:** Nutzt `st.session_state` für Chat-History und Drafts.
* **Logik:** Ruft `/chat` und `/feedback` Endpoints der API auf.
* **Anpassung:** CSS Styles sind direkt in `ui.py` eingebettet.
---
## 4. Tests & Debugging
@@ -179,20 +188,16 @@ Prüfen den Datenfluss von Markdown bis Qdrant-JSON.
python3 -m scripts.edges_full_check
### 4.3 Smoke Tests (E2E)
Prüfen das laufende System (API) gegen eine echte Qdrant-Instanz und Ollama.
Prüfen das laufende System gegen eine echte Qdrant-Instanz und Ollama.
# 1. Retriever Test (Hybrid + Explanation)
python scripts/test_retriever_smoke.py --query "Test" --mode hybrid --top-k 5 --explain
# 2. Decision Engine Test (WP06)
# Prüft Intent, Retrieval und Reasoning (mit Timeout-Handling)
# 1. API Test (Decision Engine)
python tests/test_wp06_decision.py -p 8002 -e DECISION -q "Soll ich X tun?"
# 3. Empathy Test (WP06)
# Prüft LLM-Router Fallback
python tests/test_wp06_decision.py -p 8002 -e EMPATHY -q "Alles ist grau"
# 2. UI Test (Manuell)
# Öffne http://localhost:8502
# Stelle eine Frage und prüfe Intent-Badge und Quellen-Anzeige.
# 4. Feedback Test (WP04c)
# 3. Feedback Test
python tests/test_feedback_smoke.py --url http://localhost:8002/query
---
@@ -260,6 +265,9 @@ Standardmäßig werden alle expliziten Kanten gleich behandelt. Wenn Kausalität
python3 tests/inspect_one_note.py --file ./vault/MeinFile.md
**Live-Logs sehen (Beelink) - inkl. LLM Thoughts:**
**Live-Logs sehen (Systemd):**
journalctl -u mindnet-dev -f
# Backend
journalctl -u mindnet-dev -f
# Frontend
journalctl -u mindnet-ui-dev -f
+16 -11
View File
@@ -1,9 +1,9 @@
# Mindnet v2.2 – Fachliche Architektur
**Datei:** `docs/mindnet_functional_architecture_v2.2.md`
**Stand:** 2025-12-09
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
**Stand:** 2025-12-10
**Status:** **FINAL** (Integrierter Stand WP01–WP10)
> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten), die Logik des Retrievers und den neuen **RAG-Chat** (Decision Engine & Persönlichkeit). Die technische Umsetzung wird im technischen Dokument detailliert.
> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten), die Logik des Retrievers und den **RAG-Chat** (Decision Engine & Persönlichkeit). Die technische Umsetzung wird im technischen Dokument detailliert.
---
<details>
@@ -38,7 +38,7 @@
- [8) Erweiterbarkeit \& Teaching (Context Intelligence)](#8-erweiterbarkeit--teaching-context-intelligence)
- [A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)](#a-workflow-einen-neuen-typ-implementieren-z-b-type-risk)
- [B. Workflow: Neue Beziehungen nutzen (z. B. `beeinflusst_von`)](#b-workflow-neue-beziehungen-nutzen-z-b-beeinflusst_von)
- [9) Feedback \& Lernen – WP04c](#9-feedback--lernen--wp04c)
- [9) Feedback \& Lernen – WP04c/WP10](#9-feedback--lernen--wp04cwp10)
- [9.1 Der Feedback-Loop](#91-der-feedback-loop)
- [10) Confidence \& Provenance – wozu?](#10-confidence--provenance--wozu)
- [11) Semantik ausgewählter `kind`-Werte](#11-semantik-ausgewählter-kind-werte)
@@ -46,7 +46,7 @@
- [13) Lösch-/Update-Garantien (Idempotenz)](#13-lösch-update-garantien-idempotenz)
- [14) Beispiel – Von Markdown zu Kanten (v2.2)](#14-beispiel--von-markdown-zu-kanten-v22)
- [15) Referenzen (Projektdateien \& Leitlinien)](#15-referenzen-projektdateien--leitlinien)
- [16) Workpackage Status (v2.3.1)](#16-workpackage-status-v231)
- [16) Workpackage Status (v2.3.2)](#16-workpackage-status-v232)
</details>
---
@@ -273,7 +273,7 @@ Mindnet lernt nicht durch klassisches Training (Fine-Tuning), sondern durch **Ko
Steuere, wie schwer der Inhalt wiegt und wie er vernetzt wird.
```yaml
risk:
chunk_profile: short # Risiken sind prägnant
chunk_profile: short # Risiken sind oft kurze Statements
retriever_weight: 0.90 # Hohe Priorität im Ranking
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
```
@@ -308,11 +308,13 @@ Beziehungen sind der Klebstoff für logische Schlussfolgerungen.
---
## 9) Feedback & Lernen – WP04c
## 9) Feedback & Lernen – WP04c/WP10
Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, das die Basis für zukünftiges Lernen bildet.
### 9.1 Der Feedback-Loop
Die Interaktion erfolgt primär über das **Web-Interface (WP10)**.
1. **Suche (Situation):**
Wenn ein Nutzer eine Anfrage stellt, loggt Mindnet die "Situation":
* Den Query-Text.
@@ -321,8 +323,8 @@ Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, da
* 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.
Der Nutzer bewertet die Antwort (**Sterne**) oder einzelne Quellen (**Faces**) im Frontend.
Dieses Feedback wird unter Referenzierung der `query_id` in `feedback.jsonl` 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.
@@ -402,7 +404,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
---
## 16) Workpackage Status (v2.3.1)
## 16) Workpackage Status (v2.3.2)
Aktueller Implementierungsstand der Module.
@@ -416,4 +418,7 @@ Aktueller Implementierungsstand der Module.
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
| **WP06** | Decision Engine | 🟢 Live | Intent-Router & Strategic Retrieval. |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
| **WP07** | Interview Assistent | 🟡 Geplant | Dialog-Modus (Nächster Schritt). |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
| **WP10** | Chat Interface | 🟢 Live | Web-UI mit Feedback & Intents. |
| **WP10a**| GUI Evolution | 🔴 Geplant | Erweiterte Interaktion. |
+59 -21
View File
@@ -1,11 +1,11 @@
# Mindnet v2.2 – Technische Architektur
**Datei:** `docs/mindnet_technical_architecture_v2.2.md`
**Stand:** 2025-12-09
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
**Stand:** 2025-12-10
**Status:** **FINAL** (Integrierter Stand WP01–WP10)
**Quellen:** `Programmplan_V2.2.md`, `Handbuch.md`, `chunking_strategy.md`, `wp04_retriever_scoring.md`.
> **Ziel dieses Dokuments:**
> Vollständige Beschreibung der technischen Architektur inkl. Graph-Datenbank, Retrieval-Logik und der **neuen RAG-Komponenten (Decision Engine & Hybrid Router)**.
> Vollständige Beschreibung der technischen Architektur inkl. Graph-Datenbank, Retrieval-Logik, der **neuen RAG-Komponenten (Decision Engine & Hybrid Router)** und dem **Frontend (Streamlit)**.
---
<details>
@@ -15,7 +15,7 @@
- [](#)
- [1. Systemüberblick](#1-systemüberblick)
- [1.1 Architektur-Zielbild](#11-architektur-zielbild)
- [1.2 Verzeichnisstruktur \& Komponenten (Post-WP06)](#12-verzeichnisstruktur--komponenten-post-wp06)
- [1.2 Verzeichnisstruktur \& Komponenten (Post-WP10)](#12-verzeichnisstruktur--komponenten-post-wp10)
- [2. Datenmodell \& Collections (Qdrant)](#2-datenmodell--collections-qdrant)
- [2.1 Notes Collection (`<prefix>_notes`)](#21-notes-collection-prefix_notes)
- [2.2 Chunks Collection (`<prefix>_chunks`)](#22-chunks-collection-prefix_chunks)
@@ -39,12 +39,16 @@
- [6.3 Schritt 2: Strategy Resolution (Late Binding)](#63-schritt-2-strategy-resolution-late-binding)
- [6.4 Schritt 3: Multi-Stage Retrieval](#64-schritt-3-multi-stage-retrieval)
- [6.5 Schritt 4: Generation \& Response](#65-schritt-4-generation--response)
- [7. Feedback \& Logging Architektur (WP04c)](#7-feedback--logging-architektur-wp04c)
- [7.1 Komponenten](#71-komponenten)
- [7.2 Log-Dateien](#72-log-dateien)
- [7.3 Traceability](#73-traceability)
- [8. Indizes \& Performance](#8-indizes--performance)
- [9. Offene Punkte / Known Limitations](#9-offene-punkte--known-limitations)
- [7. Frontend Architektur (WP10)](#7-frontend-architektur-wp10)
- [7.1 Kommunikation](#71-kommunikation)
- [7.2 Features \& UI-Logik](#72-features--ui-logik)
- [7.3 Deployment Ports](#73-deployment-ports)
- [8. Feedback \& Logging Architektur (WP04c)](#8-feedback--logging-architektur-wp04c)
- [8.1 Komponenten](#81-komponenten)
- [8.2 Log-Dateien](#82-log-dateien)
- [8.3 Traceability](#83-traceability)
- [9. Indizes \& Performance](#9-indizes--performance)
- [10. Offene Punkte / Known Limitations](#10-offene-punkte--known-limitations)
</details>
@@ -53,18 +57,19 @@
## 1. Systemüberblick
### 1.1 Architektur-Zielbild
Mindnet ist ein **lokales RAG-System (Retrieval Augmented Generation)**.
Mindnet ist ein **lokales RAG-System (Retrieval Augmented Generation)** mit Web-Interface.
1. **Source:** Markdown-Notizen in einem Vault (Obsidian-kompatibel).
2. **Pipeline:** Ein Python-Importer transformiert diese in **Notes**, **Chunks** und **Edges**.
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.
5. **Inference:** Lokales LLM (Ollama: Phi-3 Mini) für RAG-Chat und Antwortgenerierung.
4. **Backend:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** sowie **Feedback** bereit.
5. **Frontend:** Streamlit-App (`ui.py`) für Interaktion und Visualisierung.
6. **Inference:** Lokales LLM (Ollama: Phi-3 Mini) für RAG-Chat und Antwortgenerierung.
Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsgetrieben** (`types.yaml`, `retriever.yaml`, `decision_engine.yaml`, `prompts.yaml`).
### 1.2 Verzeichnisstruktur & Komponenten (Post-WP06)
### 1.2 Verzeichnisstruktur & Komponenten (Post-WP10)
/mindnet/
├── app/
@@ -89,6 +94,8 @@ Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsge
│ │ ├── llm_service.py # Ollama Client mit Timeout & Raw-Mode
│ │ ├── feedback_service.py # JSONL Logging (WP04c)
│ │ └── embeddings_client.py
│ ├── frontend/ # NEU (WP10)
│ └── ui.py # Streamlit Application
├── config/
│ ├── types.yaml # Typ-Definitionen (Import-Zeit)
│ ├── retriever.yaml # Scoring-Gewichte (Laufzeit)
@@ -134,6 +141,7 @@ Die atomaren Sucheinheiten.
| :--- | :--- | :--- |
| `chunk_id` | Keyword | Deterministisch: `{note_id}#c{index:02d}`. |
| `note_id` | Keyword | Referenz zur Note. |
| `type` | Keyword | **Kopie des Note-Typs** (Denormalisiert für Filter). |
| `text` | Text | **Reiner Inhalt** (ohne Overlap). Anzeige-Text. |
| `window` | Text | **Kontext-Fenster** (mit Overlap). Embedding-Basis. |
| `ord` | Integer | Sortierreihenfolge (1..N). |
@@ -307,15 +315,44 @@ Basierend auf dem Intent lädt der Router die Parameter:
---
## 7. Feedback & Logging Architektur (WP04c)
## 7. Frontend Architektur (WP10)
Das Frontend ist eine **Streamlit-Anwendung**, die als separater Prozess läuft und via HTTP mit dem Backend kommuniziert.
### 7.1 Kommunikation
* **Backend-URL:** Konfiguriert via `MINDNET_API_URL` (Default: `http://localhost:8002`).
* **Endpoints:** Nutzt `/chat` für Interaktion und `/feedback` für Bewertungen.
* **Resilienz:** Das Frontend implementiert eigene Timeouts (`MINDNET_API_TIMEOUT`, Default 300s), um lange Wartezeiten lokaler LLMs abzufangen.
### 7.2 Features & UI-Logik
* **State Management:** Session-State speichert Chat-Verlauf und `query_id` für Feedback.
* **Visualisierung:**
* **Intent Badges:** Zeigt Router-Entscheidung (`DECISION`, `FACT`, etc.) und Quelle (`Keyword` vs. `LLM`).
* **Source Expanders:** Zeigt verwendete Chunks inkl. Score und "Why"-Explanation.
* **Sidebar:** Zeigt Suchhistorie (Log-basiert) und Konfiguration.
* **Feedback:**
* Global (Antwort): 1-5 Sterne Rating.
* Granular (Quellen): Faces-Rating (Mapped auf 1-5 Score).
### 7.3 Deployment Ports
Zur sauberen Trennung von Prod und Dev laufen Frontend und Backend auf dedizierten Ports:
| Umgebung | Backend (FastAPI) | Frontend (Streamlit) |
| :--- | :--- | :--- |
| **Production** | 8001 | 8501 |
| **Development** | 8002 | 8502 |
---
## 8. Feedback & Logging Architektur (WP04c)
Mindnet implementiert ein "Data Flywheel" zur späteren Optimierung (Self-Tuning).
### 7.1 Komponenten
### 8.1 Komponenten
* **Feedback Service (`app/services/feedback_service.py`):** Kapselt die Schreibzugriffe.
* **Storage:** Lokales Dateisystem (`data/logs/`), Format JSONL (Line-delimited JSON).
### 7.2 Log-Dateien
### 8.2 Log-Dateien
1. **`search_history.jsonl`**:
* Speichert jede Anfrage an `/query` und `/chat`.
* Enthält: `query_id`, `query_text`, `timestamp`, `hits` (inkl. `score_breakdown` Snapshots).
@@ -323,27 +360,28 @@ Mindnet implementiert ein "Data Flywheel" zur späteren Optimierung (Self-Tuning
2. **`feedback.jsonl`**:
* Speichert User-Reaktionen an `/feedback`.
* Enthält: `query_id`, `node_id`, `score` (1-5), `comment`.
* **Granularität:** Kann sich auf `generated_answer` (Global) oder eine spezifische `node_id` (Quelle) beziehen.
* Zweck: Labels ("War es gut?").
### 7.3 Traceability
### 8.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.
---
## 8. Indizes & Performance
## 9. Indizes & Performance
Damit Qdrant performant bleibt, sind Payload-Indizes essenziell.
**Erforderliche Indizes:**
* **Notes:** `note_id`, `type`, `tags`.
* **Chunks:** `note_id`, `chunk_id`.
* **Chunks:** `note_id`, `chunk_id`, `type`.
* **Edges:** `source_id`, `target_id`, `kind`, `scope`, `note_id`.
Validierung erfolgt über `tests/ensure_indexes_and_show.py`.
---
## 9. Offene Punkte / Known Limitations
## 10. Offene Punkte / Known Limitations
1. **Multi-Target Inline-Relations:**
* `rel: similar_to [[A]] [[B]]` wird aktuell parser-seitig nicht unterstützt.
+30 -7
View File
@@ -1,7 +1,7 @@
# mindnet v2.2 – Pipeline Playbook
**Datei:** `docs/mindnet_pipeline_playbook_v2.2.md`
**Stand:** 2025-12-09
**Status:** **FINAL** (Inkl. WP06 Decision Engine)
**Stand:** 2025-12-10
**Status:** **FINAL** (Inkl. WP10 Frontend)
**Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `mindnet_admin_guide_v2.2.md`.
---
@@ -33,6 +33,7 @@
- [7.2 Smoke-Test (E2E)](#72-smoke-test-e2e)
- [8. Ausblick \& Roadmap (Technische Skizzen)](#8-ausblick--roadmap-technische-skizzen)
- [8.1 WP-08: Self-Tuning (Skizze)](#81-wp-08-self-tuning-skizze)
- [16. Workpackage Status (v2.3.2)](#16-workpackage-status-v232)
</details>
---
@@ -43,7 +44,7 @@ Dieses Playbook ist das zentrale operative Handbuch für die **mindnet-Pipeline*
**Zielgruppe:** Dev/Ops, Tech-Leads.
**Scope:**
* **Ist-Stand (WP01–WP06):** Import, Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat (Hybrid Router), Feedback Loop.
* **Ist-Stand (WP01–WP10):** Import, Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat (Hybrid Router), Feedback Loop, Frontend.
* **Roadmap (Ausblick):** Technische Skizze für Self-Tuning (WP08).
---
@@ -88,10 +89,11 @@ Für regelmäßige Updates (z.B. Cronjob). Erkennt Änderungen via Hash.
* `--sync-deletes`: Entfernt Notizen aus Qdrant, die im Vault gelöscht wurden.
### 2.3 Deployment & Restart (Systemd)
Nach einem Import oder Code-Update muss der API-Prozess neu gestartet werden.
Nach einem Import oder Code-Update müssen die API-Prozesse neu gestartet werden.
# Neustart des Produktions-Services
# Neustart des Produktions-Services (API + UI)
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod
# Prüfung
sudo systemctl status mindnet-prod
@@ -203,7 +205,7 @@ Prüft am laufenden System (Prod oder Dev), ob Semantik, Graph und Feedback funk
# Retriever Test
python scripts/test_retriever_smoke.py --mode hybrid --top-k 5
# Chat / Decision Engine Test (Neu WP06)
# Decision Engine Test (WP06)
python tests/test_wp06_decision.py -p 8002 -e EMPATHY -q "Alles ist grau"
# Feedback Test
@@ -220,4 +222,25 @@ Wie entwickeln wir die Pipeline weiter?
**Ansatz:** Ein Offline-Learning-Skript `scripts/optimize_weights.py`.
1. **Load:** Liest `search_history.jsonl` und joint mit `feedback.jsonl` via `query_id`.
2. **Analyze:** Korrelation Scores vs. User-Rating.
3. **Optimize:** Vorschlag neuer Gewichte für `retriever.yaml`.
3. **Optimize:** Vorschlag neuer Gewichte für `retriever.yaml`.
---
## 16. Workpackage Status (v2.3.2)
Aktueller Implementierungsstand der Module.
| WP | Titel | Status | Anmerkung |
| :--- | :--- | :--- | :--- |
| **WP01** | Knowledge Design | 🟢 Live | Typen, Frontmatter definiert. |
| **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 | 🟢 Live | API liefert Reasons & Breakdown. |
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
| **WP06** | Decision Engine | 🟢 Live | Hybrid Router, Strategic Retrieval. |
| **WP07** | Interview Assistent | 🟡 Geplant | Nächster Schritt (Dialog-Modus). |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
| **WP10** | Chat Interface | 🟢 Live | Streamlit Web-UI mit Feedback & Intents. |
| **WP10a**| GUI Evolution | 🔴 Geplant | Draft-Editor & Interaktionstools. |
+57 -47
View File
@@ -1,7 +1,7 @@
# Mindnet v2.2 – User Guide
**Datei:** `docs/mindnet_user_guide_v2.2.md`
**Stand:** 2025-12-09
**Status:** **FINAL** (Inkl. RAG & Multi-Personality Chat)
**Stand:** 2025-12-10
**Status:** **FINAL** (Inkl. RAG & Web-Interface)
**Quellen:** `knowledge_design.md`, `wp04_retriever_scoring.md`, `Programmplan_V2.2.md`, `Handbuch.md`.
> **Willkommen bei Mindnet.**
@@ -20,7 +20,7 @@ Wenn du nach "Projekt Alpha" suchst, findet Mindnet nicht nur das Dokument. Es f
* **Ähnliches:** "Projekt Beta war ähnlich".
### 1.2 Der Zwilling (Die Personas)
Seit Version 2.3.1 passt Mindnet seinen Charakter dynamisch an deine Frage an:
Mindnet passt seinen Charakter dynamisch an deine Frage an:
1. **Der Bibliothekar (FACT):** Liefert präzise Fakten und Definitionen.
2. **Der Berater (DECISION):** Hilft dir beim Abwägen, basierend auf deinen Werten und Zielen.
3. **Der Spiegel (EMPATHY):** Hört zu und antwortet basierend auf deinen Erfahrungen ("Ich"-Perspektive).
@@ -28,11 +28,32 @@ Seit Version 2.3.1 passt Mindnet seinen Charakter dynamisch an deine Frage an:
---
## 2. Den Chat steuern (Intents)
## 2. Die Oberfläche (Web UI)
Seit Version 2.3.1 bedienst du Mindnet über eine grafische Oberfläche im Browser.
### 2.1 Der Chat-Bereich
* **Eingabe:** Unten findest du das Textfeld.
* **Intent-Badge:** Über jeder Antwort zeigt ein kleines Label (z.B. **⚖️ Intent: DECISION**), in welchem Modus das System arbeitet und ob dies durch ein Schlüsselwort oder die KI erkannt wurde.
* **Quellen-Karten:** Unter der Antwort findest du ausklappbare Karten ("Expanders").
* **Grüner Punkt:** Hohe Relevanz (Score > 0.8).
* **Gelber Punkt:** Mittlere Relevanz.
* **Klick darauf:** Zeigt den Textauszug und die **Begründung** ("Warum wurde das gefunden?").
### 2.2 Die Sidebar (Einstellungen & Verlauf)
* **Modus-Wahl:** Umschalten zwischen "💬 Chat" und "📝 Neuer Eintrag" (Vorbereitung für WP07).
* **Verlauf:** Die letzten Suchanfragen sind hier gelistet. Ein Klick führt die Suche erneut aus.
* **Settings:**
* **Top-K:** Wie viele Quellen sollen gelesen werden? (Standard: 5).
* **Explanation Layer:** Schaltet die "Warum"-Erklärungen an/aus.
---
## 3. Den Chat steuern (Intents)
Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Das System nutzt einen **Hybrid Router**, der sowohl auf Schlüsselwörter als auch auf die Bedeutung achtet.
### 2.1 Modus: Entscheidung ("Der Berater")
### 3.1 Modus: Entscheidung ("Der Berater")
Wenn du vor einer Wahl stehst, hilft Mindnet dir, konform zu deinen Prinzipien zu bleiben.
* **Auslöser (Keywords):** "Soll ich...", "Was ist deine Meinung?", "Strategie für...", "Vor- und Nachteile".
@@ -41,68 +62,57 @@ Wenn du vor einer Wahl stehst, hilft Mindnet dir, konform zu deinen Prinzipien z
* *Du:* "Soll ich Tool X nutzen?"
* *Mindnet:* "Nein. Tool X speichert Daten in den USA. Das verstößt gegen dein Prinzip 'Privacy First' und dein Ziel 'Digitale Autarkie'."
### 2.2 Modus: Empathie ("Der Spiegel")
### 3.2 Modus: Empathie ("Der Spiegel")
Wenn du frustriert bist oder reflektieren willst, wechselt Mindnet in den "Ich"-Modus.
* **Auslöser (Keywords & Semantik):** "Ich fühle mich...", "Traurig", "Gestresst", "Alles ist sinnlos", "Ich bin überfordert".
* **Was passiert:** Mindnet lädt deine **Erfahrungen** (`type: experience`) und **Glaubenssätze** (`type: belief`). Es antwortet verständnisvoll und zitiert deine eigenen Lektionen.
* **Beispiel-Dialog:**
* *Du:* "Ich bin total überfordert, nichts funktioniert."
* *Mindnet:* "Das Gefühl kenne ich. Erinnere dich an die Situation im Projekt X ('Der Durchbruch nach der Krise'). Damals hat uns das Mantra 'Einfach weitermachen, der Nebel lichtet sich' geholfen."
### 2.3 Modus: Coding ("Der Techniker")
* **Auslöser:** "Code", "Python", "Funktion", "Syntax".
* **Was passiert:** Mindnet antwortet kurz, prägnant und liefert Code-Blöcke. Smalltalk wird reduziert.
### 2.4 Modus: Fakten (Standard)
### 3.3 Modus: Fakten (Standard)
* **Auslöser:** Alles andere. "Was ist Qdrant?", "Zusammenfassung von X".
* **Was passiert:** Standard-Suche nach Wissen ohne spezielle Filter.
---
## 3. Ergebnisse interpretieren (Explanation Layer)
## 4. Ergebnisse interpretieren (Explanation Layer)
Mindnet liefert nicht einfach nur Treffer. Es liefert eine **Begründung** (Explanation), warum es etwas gefunden hat.
### 3.1 Die Gründe ("Reasons")
Das System sagt dir in natürlicher Sprache, warum ein Treffer relevant ist:
### 4.1 Die Gründe ("Reasons")
Öffne eine Quellen-Karte, um zu sehen:
* *"Hohe textuelle Übereinstimmung."* (Semantik)
* *"Bevorzugt aufgrund des Typs 'decision'."* (Wichtigkeit)
* *"Verweist auf 'Projekt X' via 'depends_on'."* (Graph-Kontext)
### 3.2 Der Score Breakdown
Wenn du es genau wissen willst, schau auf die Aufschlüsselung:
Score = (Text) + (Typ-Bonus) + (Vernetzungs-Bonus)
---
## 4. Neues Wissen beisteuern (Authoring)
Mindnet lebt von deinem Input. Du musst kein Techniker sein, um gutes Wissen zu designen. Siehe dazu das **Knowledge Design Manual** für Details.
### 4.1 Die Goldene Regel: "Verlinke semantisch"
Statt einfach nur `[[Link]]` zu schreiben, versuche zu sagen, *wie* es zusammenhängt.
* Hängt es davon ab? -> `[[rel:depends_on Ziel]]`
* Ist es ähnlich? -> `[[rel:similar_to Ziel]]`
### 4.2 Typen nutzen (Wichtig!)
Setze im Frontmatter deiner Notizen den richtigen Typ. Das ist der wichtigste Hebel für den Chat:
* Willst du, dass Mindnet etwas als **Regel** nutzt? -> `type: principle`
* Willst du, dass Mindnet dich an eine **Lektion** erinnert? -> `type: experience`
---
## 5. Feedback & Lernen
Mindnet wird schlauer, wenn du es pflegst.
Mindnet wird schlauer, wenn du es pflegst. Nutze die Feedback-Funktionen im Chat:
### 5.1 Feedback geben (Data Flywheel)
Das System zeichnet auf, welche Ergebnisse es liefert. Du kannst Treffer bewerten (geplant für WP-10 UI).
In Zukunft analysiert das System diese Daten, um seine Gewichte selbstständig anzupassen (Self-Tuning).
### 5.1 Globales Feedback (Antwort-Qualität)
* **Wie:** Klicke auf die **Sterne (1-5)** unter der Antwort.
* **Bedeutung:** Bewertet, wie gut die generierte Antwort war (Prompting, Tonfall).
### 5.2 Ergebnis fehlt? Troubleshooting
Wenn Mindnet etwas nicht findet:
1. **Existiert** die Notiz im Vault? (Dateiname korrekt?)
2. **Typ korrekt?** (Eine Erfahrung als `concept` getaggt wird im Empathie-Modus vielleicht übersehen).
3. **Keywords?** (Wenn du "grau" sagst, aber in der Notiz nur "schlecht" steht, füge das Wort "grau" zur Notiz hinzu).
### 5.2 Granulares Feedback (Quellen-Relevanz)
* **Wie:** Klicke innerhalb einer Quellen-Karte auf die **Smileys (Faces)**.
* **Bedeutung:**
* 😞 (Sad): Diese Quelle ist irrelevant/falsch. (Senkt zukünftig das Gewicht).
* 😐 (Neutral): Okay, aber nicht entscheidend.
* 😀 (Grin): Das ist der perfekte Treffer! (Stärkt diesen Typ/Kante).
---
## 6. Neues Wissen beisteuern (Authoring)
Mindnet lebt von deinem Input. Du musst kein Techniker sein, um gutes Wissen zu designen. Siehe dazu das **Knowledge Design Manual** für Details.
### 6.1 Die Goldene Regel: "Verlinke semantisch"
Statt einfach nur `[[Link]]` zu schreiben, versuche zu sagen, *wie* es zusammenhängt.
* Hängt es davon ab? -> `[[rel:depends_on Ziel]]`
* Ist es ähnlich? -> `[[rel:similar_to Ziel]]`
### 6.2 Typen nutzen (Wichtig!)
Setze im Frontmatter deiner Notizen den richtigen Typ. Das ist der wichtigste Hebel für den Chat:
* Willst du, dass Mindnet etwas als **Regel** nutzt? -> `type: principle`
* Willst du, dass Mindnet dich an eine **Lektion** erinnert? -> `type: experience`
+4 -6
View File
@@ -11,25 +11,23 @@ qdrant-client>=1.15.1
pydantic>=2.11.7
numpy>=2.3.2
# --- Markdown & Parsing (Hier fehlten Pakete!) ---
# --- Markdown & Parsing ---
python-frontmatter>=1.1.0
# WICHTIG: Das fehlte und verursachte den Fehler
markdown-it-py>=3.0.0
# WICHTIG: Für types.yaml und retriever.yaml
PyYAML>=6.0.2
python-slugify>=8.0.4
# --- KI & Embeddings ---
sentence-transformers>=5.1.0
# Torch wird meist durch sentence-transformers geholt,
# aber wir listen es explizit für Stabilität
torch>=2.0.0
# --- Utilities ---
# WICHTIG: Damit .env Dateien gelesen werden
python-dotenv>=1.1.1
requests>=2.32.5
tqdm>=4.67.1
# --- Testing ---
pytest>=8.4.2
# --- Frontend (WP-10) ---
streamlit>=1.39.0
+29 -10
View File
@@ -1,6 +1,10 @@
"""
tests/test_wp06_decision.py — Flexibler Integrationstest für WP-06
Update: Timeout auf 300s erhöht für CPU-Inference Cold-Starts.
Update:
- Timeout 300s.
- Zeigt Intent Source an.
- Payload/Source Fallback für Metadaten.
- Debug-Dump bei unknown Type.
"""
import requests
import json
@@ -22,7 +26,7 @@ def test_decision_engine(query: str, port: int, expected_intent: str):
print(f"FRAGE: '{query}'")
print("... warte auf LLM (kann auf CPU >120s dauern) ...")
# FIX: Timeout auf 300 erhöht, passend zur Server-Config
# FIX: Timeout auf 300 erhöht
response = requests.post(f"{api_url}/chat/", json=payload, timeout=300)
response.raise_for_status()
data = response.json()
@@ -31,9 +35,14 @@ def test_decision_engine(query: str, port: int, expected_intent: str):
# 1. Intent Check
intent = data.get("intent", "UNKNOWN")
match = intent == expected_intent
source_method = data.get("intent_source", "Unknown Source")
match = intent.upper() == expected_intent.upper()
print(f"\n1. INTENT DETECTION: [{'✅' if match else '❌'}]")
print(f" Erkannt: {intent} (Erwartet: {expected_intent})")
print(f" Erkannt: {intent}")
print(f" Erwartet: {expected_intent}")
print(f" Methode: {source_method}")
# 2. Source Check (Strategic Retrieval)
sources = data.get("sources", [])
@@ -44,18 +53,28 @@ def test_decision_engine(query: str, port: int, expected_intent: str):
if not sources:
print(" (Keine Quellen gefunden)")
debug_printed = False
for i, source in enumerate(sources):
# Safe access auf Source-Dict
src_meta = source.get("source", {})
# --- FIX: Robusterer Zugriff auf Metadaten ---
src_meta = source.get("payload") or source.get("source") or {}
node_type = src_meta.get("type", "unknown")
title = source.get("note_id", "Unknown")
score = source.get("total_score", 0.0)
# DEBUG: Wenn Typ unknown ist, dumpen wir das erste Objekt
if node_type == "unknown" and not debug_printed:
print(f"\n 🔴 DEBUG: Raw Data von Quelle {i+1} (da Typ unknown):")
print(json.dumps(source, indent=2, ensure_ascii=False))
print(" ------------------------------------------------")
debug_printed = True
# Marker für Ausgabe
marker = " "
if node_type in ["value", "principle", "goal", "experience", "belief", "profile"]:
if node_type in ["value", "principle", "goal", "experience", "belief", "profile", "decision"]:
marker = "🎯" # Strategischer Treffer
strategic_hits.append(title)
strategic_hits.append(f"{title} ({node_type})")
else:
marker = "📄"
fact_hits.append(title)
@@ -77,7 +96,7 @@ def test_decision_engine(query: str, port: int, expected_intent: str):
except requests.exceptions.ReadTimeout:
print(f"\n❌ TIMEOUT: Der Server hat nicht innerhalb von 300s geantwortet.")
print(" Tipp: Prüfe die Server-Logs. Lädt er noch das Modell?")
print(" Tipp: Prüfe die Server-Logs (Terminal 1). Lädt er noch das Modell?")
sys.exit(1)
except requests.exceptions.ConnectionError:
print(f"\n❌ FEHLER: Keine Verbindung zu {api_url}. Läuft der Server?")
@@ -96,7 +115,7 @@ if __name__ == "__main__":
help="Der Port der API (Default: 8002 für Dev).")
parser.add_argument("--expect", "-e", type=str,
default="DECISION",
help="Der erwartete Intent (z.B. DECISION, EMPATHY).")
help="Der erwartete Intent (z.B. DECISION, EMPATHY, FACT).")
args = parser.parse_args()