Compare commits
78
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
046aa2cf48 | ||
|
|
0bc0e66a85 | ||
|
|
2310633de3 | ||
|
|
bd36d78025 | ||
|
|
d2270fafdd | ||
|
|
86faf5b8f0 | ||
|
|
902f26ee95 | ||
|
|
ea9fe1a6ed | ||
|
|
6c2074166c | ||
|
|
bd44af2b68 | ||
|
|
972cd0dfac | ||
|
|
9cc16bb220 | ||
|
|
03594424a1 | ||
|
|
97985371ca | ||
|
|
3c5c01998f | ||
|
|
2fa24cb1bd | ||
|
|
0304bae9f4 | ||
|
|
ac6d34731a | ||
|
|
be5ad7e080 | ||
|
|
32128c06c1 | ||
|
|
07b7f419de | ||
|
|
4d6fce2d93 | ||
|
|
b398168b1f | ||
|
|
6b397fea2e | ||
|
|
d20386e0a7 | ||
|
|
fcb90db2d0 | ||
|
|
5d8e96372f | ||
|
|
0d1a98279e | ||
|
|
73641abf8a | ||
|
|
a4873b3d45 | ||
|
|
4f171e5245 | ||
|
|
d48b671314 | ||
|
|
b9d73af062 | ||
|
|
21904e62ee | ||
|
|
f9af30b195 | ||
|
|
531e3790b3 | ||
|
|
7745b71832 | ||
|
|
b39663408c | ||
|
|
9c4696e9d5 | ||
|
|
cf5e53f341 | ||
|
|
e512f768ff | ||
|
|
c3ef65d069 | ||
|
|
90f0be6baf | ||
|
|
eba51eba0f | ||
|
|
fbaa07ba88 | ||
|
|
d0ecc5316f | ||
|
|
9ee39277ae | ||
|
|
9d3fd21c88 | ||
|
|
d7217672a3 | ||
|
|
e39b685b1e | ||
|
|
5b9399361d | ||
|
|
7631b93900 | ||
|
|
f98eb8fc16 | ||
|
|
ab60106fb9 | ||
|
|
caab41a760 | ||
|
|
78d8ab11ed | ||
|
|
d49da1b5fe | ||
|
|
27497fd6be | ||
|
|
466ce3ca82 | ||
|
|
8b5af5ec65 | ||
|
|
34cbc0c0eb | ||
|
|
52ff4bbff5 | ||
|
|
9e7104e362 | ||
|
|
882ae5368f | ||
|
|
12a424ce23 | ||
|
|
c3230761e8 | ||
|
|
f5104008c2 | ||
|
|
013e8c6d0c | ||
|
|
603bba533b | ||
|
|
e202a8d88b | ||
|
|
c56a31c6bc | ||
|
|
b73b18bf9a | ||
|
|
0f351252b2 | ||
|
|
d7d7411fa0 | ||
|
|
45af7f074c | ||
|
|
70ab118612 | ||
|
|
ba0cdea9d0 | ||
|
|
09500ff764 |
No files matched your search
Vendored
+3
@@ -0,0 +1,3 @@
|
|||||||
|
{
|
||||||
|
"CodeGPT.apiKey": "Google AI Studio"
|
||||||
|
}
|
||||||
@@ -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.
|
||||||
@@ -0,0 +1,465 @@
|
|||||||
|
# mindnet v2.2 – Dokumentationsrahmenplan
|
||||||
|
**Datei:** `docs/mindnet_docs_master_plan_v2.2.md`
|
||||||
|
**Stand:** 2025-12-06
|
||||||
|
**Bezug:** Programmplan mindnet v2.2 :contentReference[oaicite:0]{index=0}
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Zweck dieses Rahmenplans
|
||||||
|
|
||||||
|
Dieser Rahmenplan definiert:
|
||||||
|
|
||||||
|
- die **Zieldokumente** der mindnet v2.2 Dokumentation,
|
||||||
|
- deren **Dateinamen, Zielgruppen, Inhalte und Quellen**,
|
||||||
|
- die **Zuordnung** zu Workpackages (WP) und Release-Tags,
|
||||||
|
- die **Regeln zum Informations-Erhalt** (keine inhaltlichen Verluste),
|
||||||
|
- die **empfohlene Bearbeitungsreihenfolge**.
|
||||||
|
|
||||||
|
Alle hier beschriebenen Zieldokumente werden als **eigene Markdown-Dateien** gepflegt und sind Teil von WP-14 _Review / Refactoring / Dokumentation_ (Phase E). :contentReference[oaicite:1]{index=1}
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Prinzipien zur Sicherung der Informationen
|
||||||
|
|
||||||
|
Um zu verhindern, dass Inhalte oder Ergebnisse verloren gehen, gelten folgende Prinzipien:
|
||||||
|
|
||||||
|
1. **Programmplan v2.2 als Masterreferenz**
|
||||||
|
- Programmauftrag, Vision, Phasenmodell und WP-Status werden **nicht verändert**, sondern nur referenziert.
|
||||||
|
- `Programmplan_V2.2.md` bleibt das führende Dokument für Ziele, WPs, Ampelstatus. :contentReference[oaicite:2]{index=2}
|
||||||
|
|
||||||
|
2. **Keine unkontrollierte Löschung von Inhalten**
|
||||||
|
- Bestehende Dokumente (`knowledge_design.md`, `chunking_strategy.md`, `mindnet_technical_architecture.md`, `Handbuch.md`, `TYPE_REGISTRY_MANUAL.md`, `docs_mindnet_retriever.md`, `wp04_retriever_scoring.md`) werden **nicht gelöscht**, sondern:
|
||||||
|
- vollständig archiviert,
|
||||||
|
- in die neuen Zieldokumente **überführt**,
|
||||||
|
- oder **explizit** in den Anhängen (I) als „legacy / historisch“ verlinkt.
|
||||||
|
|
||||||
|
3. **Explizite Quellenzuordnung („Building Blocks“)**
|
||||||
|
- Für jede Sektion eines Zieldokuments wird angegeben, aus **welchen bestehenden Dateien und Abschnitten** der Inhalt stammt.
|
||||||
|
- Neue Inhalte (z. B. User Guide H) werden klar als „neu, v2.2“ gekennzeichnet.
|
||||||
|
|
||||||
|
4. **Ist-Stand vs. Roadmap trennen**
|
||||||
|
- Implementierter Stand v2.2: WP01–WP04a (🟢) mit Importer, Chunking, Edge-Pipeline, Typ-Registry und hybrider Retriever.
|
||||||
|
- Geplante Features (Self-Healing, Virtual Schema Layer, Explanation Layer, Feedback-Logging, MCP-Agenten) werden als **Roadmap-Funktionen** kenntlich gemacht (Phase B–D, WPs 05–13).
|
||||||
|
|
||||||
|
5. **Versionierbarkeit**
|
||||||
|
- Alle Zieldokumente tragen im Kopf eine **Version** und **Stand-Datum** sowie optional einen Verweis auf den letzten Gitea-Tag (z. B. `mindnet_v2.2_docs_initial`, `WP04a-Retriever_final`). :contentReference[oaicite:6]{index=6}
|
||||||
|
- Änderungen werden im Abschnitt „Changelog“ der jeweiligen Datei notiert.
|
||||||
|
|
||||||
|
6. **Keine funktionalen Annahmen ohne Verifikation**
|
||||||
|
- Wo das Verhalten nicht eindeutig aus Code-/Handbuch-/WP-Dokumenten hervorgeht, wird der Punkt zunächst als _offene Frage_ markiert und nicht als Tatsache dokumentiert.
|
||||||
|
- Verifizierte Funktionen (z. B. `import_markdown`, Edge-Schema, `types.yaml`, `/query`, Scoring-Formel) werden exakt gemäß der bestehenden Dokumente beschrieben.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Zieldokumente der mindnet v2.2 Dokumentation
|
||||||
|
|
||||||
|
### 3.1 Übersichtstabelle
|
||||||
|
|
||||||
|
| ID | Zieldatei | Rolle/Zielgruppe | Hauptquellen (Building Blocks) |
|
||||||
|
|----|------------------------------------------|---------------------------------------------|--------------------------------|
|
||||||
|
| A | `mindnet_overview_v2.2.md` | Einstieg für alle Rollen | Programmplan v2.2, Knowledge Design |
|
||||||
|
| B | `mindnet_functional_architecture_v2.2.md`| Architekt:innen, Mindmaster | Knowledge Design, Functional Architecture, Programmplan |
|
||||||
|
| C | `mindnet_technical_architecture_v2.2.md` | Entwickler:innen, Tech-Architekt:innen | mindnet_technical_architecture, chunking_strategy, Handbuch |
|
||||||
|
| D | `mindnet_knowledge_design_manual_v2.2.md`| Vault-Autor:innen, Mindmaster, Analyst:innen| knowledge_design, TYPE_REGISTRY_MANUAL, Functional Architecture |
|
||||||
|
| E | `mindnet_pipeline_playbook_v2.2.md` | Dev/Ops, Tech-Lead | mindnet_v2_implementation_playbook, Handbuch, chunking_strategy, docs_mindnet_retriever, wp04_retriever_scoring |
|
||||||
|
| F | `mindnet_developer_guide_v2.2.md` | Entwickler:innen (Code, API, Tests) | Technical Architecture, Handbuch, docs_mindnet_retriever |
|
||||||
|
| G | `mindnet_admin_guide_v2.2.md` | Admins, Betreiber | Handbuch, Implementation Playbook, Programmplan (Governance) |
|
||||||
|
| H | `mindnet_user_guide_v2.2.md` | Endnutzer:innen, Agent-User | Knowledge Design, Programmplan (Use Cases), spätere MCP-WPs |
|
||||||
|
| I | `mindnet_appendices_v2.2.md` | Alle Rollen (Referenzen, Tabellen) | TYPE_REGISTRY_MANUAL, chunking_strategy, WP-Übersicht, Edge-Referenz |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Detailpläne pro Zieldokument (Inhaltsverzeichnis & Building Blocks)
|
||||||
|
|
||||||
|
### A) `mindnet_overview_v2.2.md`
|
||||||
|
|
||||||
|
#### Zweck & Zielgruppe
|
||||||
|
- Einstieg in mindnet für alle Rollen (Owner, Mindmaster, Developer, Admin, Agenten-Entwickler).
|
||||||
|
- Auf 3–5 Seiten: _Was ist mindnet? Wie ist es gedacht? Wie lese ich die Dokumentation?_ :contentReference[oaicite:17]{index=17}
|
||||||
|
|
||||||
|
#### Geplantes Inhaltsverzeichnis
|
||||||
|
|
||||||
|
1. **Einführung**
|
||||||
|
1. Programmauftrag & Vision (v2.2)
|
||||||
|
2. Was mindnet ist – und was nicht
|
||||||
|
2. **Drei Ebenen von mindnet**
|
||||||
|
1. Content-Ebene (Vault, Notes, Chunks)
|
||||||
|
2. Semantische Ebene (Edges, Typen, Retriever)
|
||||||
|
3. Identitäts- / Persönlichkeits-Ebene (Werte, Entscheidungen, Profile – Roadmap)
|
||||||
|
3. **End-to-End-Überblick**
|
||||||
|
1. Datenfluss: Vault → Import → Qdrant → Retriever → Antwort
|
||||||
|
2. WP-Phasenmodell (A–E) und aktueller Stand (WP01–04a grün)
|
||||||
|
4. **Rollen & Perspektiven**
|
||||||
|
1. Mindmaster / Owner
|
||||||
|
2. Autor:in (Vault-Notes)
|
||||||
|
3. Developer / Architect
|
||||||
|
4. Administrator:in
|
||||||
|
5. Agenten & LLMs (MCP-Perspektive)
|
||||||
|
5. **Leserführung durch die Dokumentation**
|
||||||
|
1. Welche Datei für welche Rolle?
|
||||||
|
2. Wie mit Ist-Stand vs. Roadmap umgehen?
|
||||||
|
6. **Glossar zentraler Begriffe**
|
||||||
|
- mindnet, Vault, Note, Chunk, Edge, Type, Identity, Self-Healing, Self-Tuning, Explanation Layer, Virtual Schema Layer, etc.
|
||||||
|
|
||||||
|
#### Building Blocks (Quellen-Mapping)
|
||||||
|
|
||||||
|
- Programmauftrag & Vision → `Programmplan_V2.2.md`, Kapitel 1–2. :contentReference[oaicite:18]{index=18}
|
||||||
|
- Phasenmodell & WPs → `Programmplan_V2.1.md`/v2.2, Kapitel 5–9 (angepasst auf v2.2-Stand).
|
||||||
|
- High-Level-Architektur → `knowledge_design.md`, Kapitel 1–3 (Ziel, Zielarchitektur, Collections). :contentReference[oaicite:20]{index=20}
|
||||||
|
- Rollenmodell → Ableitung aus Knowledge Design + Programmplan (Owner, Agenten, MCP-WPs).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### B) `mindnet_functional_architecture_v2.2.md`
|
||||||
|
|
||||||
|
#### Zweck & Zielgruppe
|
||||||
|
- Fachliche Architektur von mindnet (Konzeptmodell).
|
||||||
|
- Für Architekt:innen, Mindmaster, Knowledge-Designer.
|
||||||
|
|
||||||
|
#### Geplantes Inhaltsverzeichnis
|
||||||
|
|
||||||
|
1. **Ziel & Einordnung**
|
||||||
|
1. Bezug zu Programmauftrag & WPs (WP01–WP07, WP10–12)
|
||||||
|
2. **Kernkonzepte**
|
||||||
|
1. Notes & Note-Typen (concept, experience, project, decision, value, principle, person, event, …)
|
||||||
|
2. Chunks & Sections
|
||||||
|
3. Edges (Struktur, explizit, inline, Default-Kanten)
|
||||||
|
4. Typen-Registry & Virtual Schema Layer (fachliche Sicht, Roadmap)
|
||||||
|
3. **Graph-Modell**
|
||||||
|
1. Knotenarten (Notes, Chunks, Identity Nodes, People)
|
||||||
|
2. Kantenarten (belongs_to, references, similar_to, depends_on, related_to, next/prev, …)
|
||||||
|
3. Scope & Provenienz (chunk vs. note, rule_id, confidence)
|
||||||
|
4. **End-to-End fachlicher Datenfluss**
|
||||||
|
1. Erfassung von Wissen (Note erstellen)
|
||||||
|
2. Import & Graphaufbau
|
||||||
|
3. Retrieval & Begründungspfade
|
||||||
|
4. Self-Healing & Retroactive Edges (WP06/07 – Roadmap)
|
||||||
|
5. **Szenarien & Use Cases**
|
||||||
|
1. Wissensspeicherung (z. B. Leitbild, Projekt, Erfahrung)
|
||||||
|
2. Entscheidungen & Why-Layer (WP04b – Roadmap)
|
||||||
|
3. Persönlichkeits-/Identitätsmodell (WP10–12 – Roadmap)
|
||||||
|
6. **Rollenmodell (fachliche Sicht)**
|
||||||
|
1. Mindmaster
|
||||||
|
2. Content-Autor:innen
|
||||||
|
3. Analyst:innen (Graph-Leser)
|
||||||
|
7. **Designprinzipien (fachlich)**
|
||||||
|
- Late Binding, Virtual Schema, Self-Healing, Minimalinvasives Schreiben etc.
|
||||||
|
|
||||||
|
#### Building Blocks
|
||||||
|
|
||||||
|
- `knowledge_design.md` – Kapitel 1–4, 6–7 (Ziel, Architektur, Collections, Identitäten, Prinzipien). :contentReference[oaicite:28]{index=28}
|
||||||
|
- `mindnet_functional_architecture.md` – alle Kapitel (Kernkonzepte, Edgetypen, Provenienz, Rollen). :contentReference[oaicite:29]{index=29}
|
||||||
|
- `chunking_strategy.md` – Edges, Datenmodell, Graph-Sicht. :contentReference[oaicite:30]{index=30}
|
||||||
|
- Programmplan – WPs 01–07, 10–12 für Roadmap-Features.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### C) `mindnet_technical_architecture_v2.2.md`
|
||||||
|
|
||||||
|
#### Zweck & Zielgruppe
|
||||||
|
- Technische Architektur des Systems: Collections, Payload-Felder, Services, Schemata.
|
||||||
|
- Für Entwickler:innen und Tech-Architekt:innen.
|
||||||
|
|
||||||
|
#### Geplantes Inhaltsverzeichnis
|
||||||
|
|
||||||
|
1. **Ziel & Scope**
|
||||||
|
1. Abgrenzung zur funktionalen Architektur
|
||||||
|
2. Bezug zu WPs 02–04a, 05 (Schema, Importer, Retriever)
|
||||||
|
2. **Systemübersicht**
|
||||||
|
1. Komponentenübersicht (Importer, Qdrant, Retriever-API, Embedding-Service, n8n/MCP-Ausblick)
|
||||||
|
2. Ports, Dienste, Hauptverzeichnisse
|
||||||
|
3. **Datenmodell in Qdrant**
|
||||||
|
1. Notes (`mindnet_notes`)
|
||||||
|
2. Chunks (`mindnet_chunks`)
|
||||||
|
3. Edges (`mindnet_edges`)
|
||||||
|
4. Optionale Collections (`mindnet_people`, zukünftige)
|
||||||
|
4. **Typ-Registry & Konfiguration**
|
||||||
|
1. `config/types.yaml` – Aufbau, Defaults, Typauflösung (Ist-Stand: Frontmatter-Overrides deaktiviert)
|
||||||
|
2. `config/retriever.yaml` – Scoringgewichte, Edge-Typ-Gewichte :contentReference[oaicite:35]{index=35}
|
||||||
|
5. **Import-Pipeline (technische Sicht)**
|
||||||
|
1. Discovery & Parsing (`import_markdown.py`)
|
||||||
|
2. Hash-/Idempotenz-Mechanismus (ENV-Variablen, Baseline-Modi)
|
||||||
|
3. Chunking (`chunker.py`, `chunk_payload.py`)
|
||||||
|
4. Edge-Erzeugung (`derive_edges.py`)
|
||||||
|
5. Roundtrip & Tests (Export & Vault-Vergleich)
|
||||||
|
6. **Retriever-Architektur**
|
||||||
|
1. API (FastAPI-Endpunkt `/query`)
|
||||||
|
2. Semantik- und Hybridmodus
|
||||||
|
3. Subgraph & Graph-API (expand)
|
||||||
|
4. Scoring-Formel und Komponenten (semantik, edges, centrality) :contentReference[oaicite:37]{index=37}
|
||||||
|
7. **Offene technische Punkte / Roadmap**
|
||||||
|
1. Explanation Layer (WP04b)
|
||||||
|
2. Feedback-Logging (WP04c)
|
||||||
|
3. Virtual Schema Layer (WP05)
|
||||||
|
4. Self-Healing & Self-Tuning (WP06–08)
|
||||||
|
|
||||||
|
#### Building Blocks
|
||||||
|
|
||||||
|
- `mindnet_technical_architecture.md` – Kerntext. :contentReference[oaicite:39]{index=39}
|
||||||
|
- `chunking_strategy.md` – Datenmodell & Chunk-Details. :contentReference[oaicite:40]{index=40}
|
||||||
|
- `Handbuch.md` – ENV, Skripte, Runbooks. :contentReference[oaicite:41]{index=41}
|
||||||
|
- `wp04_retriever_scoring.md` / `docs_mindnet_retriever.md` – Retriever-Details. :contentReference[oaicite:42]{index=42}
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### D) `mindnet_knowledge_design_manual_v2.2.md`
|
||||||
|
|
||||||
|
#### Zweck & Zielgruppe
|
||||||
|
- Konkrete Anleitung für das Schreiben und Strukturieren von Notes & Chunks im Vault.
|
||||||
|
- Für dich als Owner/Mindmaster und alle, die Notes erstellen.
|
||||||
|
|
||||||
|
#### Geplantes Inhaltsverzeichnis
|
||||||
|
|
||||||
|
1. **Zweck & Scope**
|
||||||
|
1. Rolle des Vaults als „Source of Truth“
|
||||||
|
2. **Note-Struktur & Frontmatter**
|
||||||
|
1. Pflicht- und optionale Felder (id, title, type, tags, status, created/updated, …)
|
||||||
|
2. Empfehlungen für IDs, Pfade und Namenskonventionen
|
||||||
|
3. **Note-Typen & Typ-Registry**
|
||||||
|
1. Übersicht der Typen (concept, project, experience, decision, value, principle, person, event, …)
|
||||||
|
2. Typ-spezifische Einsatzempfehlungen
|
||||||
|
3. Zusammenspiel mit `types.yaml` (retriever_weight, chunk_profile, edge_defaults)
|
||||||
|
4. **Edges & Referenzen in Notes**
|
||||||
|
1. Wikilinks (`[[Note]]`) → `references`
|
||||||
|
2. Inline-Relationen (`[[rel:depends_on XYZ]]`, `similar_to`, `related_to`)
|
||||||
|
3. Callout-Edges (`> [!edge] …`)
|
||||||
|
4. Strukturkanten (Ordner, belongs_to)
|
||||||
|
5. **Best Practices**
|
||||||
|
1. Beispiele für gut modellierte Notes (Projekt, Entscheidung, Erfahrung)
|
||||||
|
2. Typische Anti-Patterns und wie man sie vermeidet
|
||||||
|
6. **Langfristige Stabilität**
|
||||||
|
1. Virtual Schema Layer – was bedeutet das für Note-Autoren? (Wenig Änderungen in bestehenden Notes, Logik in Configs) :contentReference[oaicite:46]{index=46}
|
||||||
|
|
||||||
|
#### Building Blocks
|
||||||
|
|
||||||
|
- `knowledge_design.md` – Kerntext + Beispiele. :contentReference[oaicite:47]{index=47}
|
||||||
|
- `TYPE_REGISTRY_MANUAL.md` – Typ-Registry & Verhalten. :contentReference[oaicite:48]{index=48}
|
||||||
|
- `mindnet_functional_architecture.md` – ergänzende Konzepte & Edges. :contentReference[oaicite:49]{index=49}
|
||||||
|
- `chunking_strategy.md` – Inline-Relationen, Edges, Datenmodell. :contentReference[oaicite:50]{index=50}
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### E) `mindnet_pipeline_playbook_v2.2.md`
|
||||||
|
|
||||||
|
#### Zweck & Zielgruppe
|
||||||
|
- End-to-End-Playbook für die gesamte Pipeline:
|
||||||
|
- Importer,
|
||||||
|
- Chunking,
|
||||||
|
- Edge-Erzeugung,
|
||||||
|
- Retriever & Scoring,
|
||||||
|
- (perspektivisch) Explanation Layer, Self-Healing, Self-Tuning.
|
||||||
|
- Für Dev/Ops und technische Leads.
|
||||||
|
|
||||||
|
#### Geplantes Inhaltsverzeichnis
|
||||||
|
|
||||||
|
1. **Zweck & Einordnung**
|
||||||
|
1. Bezug zu WPs 02–04a (Ist) und 04b–08 (Roadmap)
|
||||||
|
2. **Import-Pipeline (Runbook-Sicht)**
|
||||||
|
1. Inputs (Vault, Config-Files, ENV)
|
||||||
|
2. Standardläufe (Initialimport, inkrementelle Updates, Sync-Deletes)
|
||||||
|
3. Baseline-Builds & Hash-Modi
|
||||||
|
3. **Chunking & Payload-Aufbau**
|
||||||
|
1. Chunk-Profile, Overlaps, Fenster
|
||||||
|
2. Feldbesetzung (`text`, `window`, `section_title`, `neighbors`, …)
|
||||||
|
4. **Edge-Erzeugung**
|
||||||
|
1. Strukturkanten (belongs_to, next, prev)
|
||||||
|
2. Explizite Edges (Wikilinks, Inline-Relationen, Callouts)
|
||||||
|
3. Typ-Default-Kanten aus `types.yaml`
|
||||||
|
5. **Retriever & Scoring**
|
||||||
|
1. Konfiguration (`retriever.yaml`, ENV)
|
||||||
|
2. Scoring-Formel und Parameter
|
||||||
|
3. Semantik- vs. Hybridmodus
|
||||||
|
4. Test- und Smoke-Suites
|
||||||
|
6. **Quality Gates & Tests**
|
||||||
|
1. Roundtrip-Tests (Vault → Qdrant → Export)
|
||||||
|
2. Chunk-Integrität und Fenster-Checks
|
||||||
|
3. Retriever-Regressionstests
|
||||||
|
7. **Ausblick: Self-Healing, Retroactive Edges, Self-Tuning**
|
||||||
|
1. Geplante Batch-Jobs und Feedback-Pipelines (WP06–08)
|
||||||
|
|
||||||
|
#### Building Blocks
|
||||||
|
|
||||||
|
- `mindnet_v2_implementation_playbook.md` – Policies, Teststrategie, KPIs. :contentReference[oaicite:57]{index=57}
|
||||||
|
- `Handbuch.md` – Skripte & Test-Runbooks. :contentReference[oaicite:58]{index=58}
|
||||||
|
- `chunking_strategy.md` – Chunk- & Edge-Strategie. :contentReference[oaicite:59]{index=59}
|
||||||
|
- `docs_mindnet_retriever.md` / `wp04_retriever_scoring.md` – Retriever-Praktiken & Tests. :contentReference[oaicite:60]{index=60}
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### F) `mindnet_developer_guide_v2.2.md`
|
||||||
|
|
||||||
|
#### Zweck & Zielgruppe
|
||||||
|
- Konzentrierte Sicht für Entwickler:innen:
|
||||||
|
- wie das Projekt strukturiert ist,
|
||||||
|
- wie man es lokal aufsetzt,
|
||||||
|
- wie man neue Features implementiert/testet.
|
||||||
|
|
||||||
|
#### Geplantes Inhaltsverzeichnis
|
||||||
|
|
||||||
|
1. **Projektstruktur**
|
||||||
|
1. Verzeichnisbaum (app/, scripts/, tests/, config/, …)
|
||||||
|
2. **Lokale Entwicklungsumgebung**
|
||||||
|
1. Abhängigkeiten, venv, ENV
|
||||||
|
2. Starten von Services (Qdrant, API, ggf. ollama)
|
||||||
|
3. **APIs & Module**
|
||||||
|
1. Importer-Skripte
|
||||||
|
2. Core-Module (Chunker, Edge-Engine, Retriever)
|
||||||
|
3. FastAPI-Endpunkte (`/query`, evtl. Admin-Endpoints)
|
||||||
|
4. **Tests & Debugging**
|
||||||
|
1. pytest-Suites
|
||||||
|
2. Logging & Diagnoseskripte
|
||||||
|
5. **Guidelines für Erweiterungen**
|
||||||
|
1. Neue Typen & Edge-Regeln
|
||||||
|
2. Änderungen am Datenmodell
|
||||||
|
3. Umgang mit Schema-Änderungen (Virtual Schema Layer)
|
||||||
|
|
||||||
|
#### Building Blocks
|
||||||
|
|
||||||
|
- `mindnet_technical_architecture.md` – Modul- & API-Beschreibungen. :contentReference[oaicite:63]{index=63}
|
||||||
|
- `Handbuch.md` – Skripte & Beispiele. :contentReference[oaicite:64]{index=64}
|
||||||
|
- `docs_mindnet_retriever.md` – API-Beispiele für den Retriever. :contentReference[oaicite:65]{index=65}
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### G) `mindnet_admin_guide_v2.2.md`
|
||||||
|
|
||||||
|
#### Zweck & Zielgruppe
|
||||||
|
- Betriebshandbuch für mindnet:
|
||||||
|
- Installation,
|
||||||
|
- Konfiguration,
|
||||||
|
- Backup/Restore,
|
||||||
|
- Monitoring,
|
||||||
|
- Troubleshooting.
|
||||||
|
|
||||||
|
#### Geplantes Inhaltsverzeichnis
|
||||||
|
|
||||||
|
1. **Zielgruppe & Scope**
|
||||||
|
2. **Initial Setup**
|
||||||
|
1. Voraussetzungen (Ubuntu, Docker/Qdrant, Python-Umgebung)
|
||||||
|
2. ENV-Variablen & Config-Files (types.yaml, retriever.yaml)
|
||||||
|
3. **Betrieb im Alltag**
|
||||||
|
1. Regelmäßige Imports
|
||||||
|
2. Umgang mit Fehlermeldungen im Importer
|
||||||
|
3. Health-Checks für Qdrant & API
|
||||||
|
4. **Update-Prozess**
|
||||||
|
1. Vorgehen bei Schema-/Code-Updates
|
||||||
|
2. Umgang mit neuen Typen und Policies
|
||||||
|
5. **Backup & Restore**
|
||||||
|
1. Qdrant-Snapshots
|
||||||
|
2. Vault-Backup (Obsidian)
|
||||||
|
3. Konsistenzprüfungen
|
||||||
|
6. **Monitoring & Logging**
|
||||||
|
1. typische Logquellen (Importer, API, n8n)
|
||||||
|
7. **Governance & Sicherheit**
|
||||||
|
1. Bezug zur Programm-Governance (WP14, MCP-Sicherheit)
|
||||||
|
|
||||||
|
#### Building Blocks
|
||||||
|
|
||||||
|
- `Handbuch.md` – Betriebsskripte & ENV. :contentReference[oaicite:69]{index=69}
|
||||||
|
- `mindnet_v2_implementation_playbook.md` – Policies/Resilienz. :contentReference[oaicite:70]{index=70}
|
||||||
|
- Programmplan – Governance / WP14. :contentReference[oaicite:71]{index=71}
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### H) `mindnet_user_guide_v2.2.md`
|
||||||
|
|
||||||
|
#### Zweck & Zielgruppe
|
||||||
|
- Anleitung für Nutzer:innen (inkl. späterer Chat-Agenten-User):
|
||||||
|
- wie man mindnet im Alltag nutzt,
|
||||||
|
- wie man Fragen stellt,
|
||||||
|
- wie man neue Gedanken einbringt.
|
||||||
|
|
||||||
|
#### Geplantes Inhaltsverzeichnis
|
||||||
|
|
||||||
|
1. **Was mindnet für dich tut**
|
||||||
|
1. Persönliches Gedächtnis
|
||||||
|
2. KI-Zwilling als Gesprächspartner :contentReference[oaicite:72]{index=72}
|
||||||
|
2. **Zugänge zu mindnet**
|
||||||
|
1. Obsidian-Vault
|
||||||
|
2. Chat-Agent (lokal, n8n-Workflows)
|
||||||
|
3. (später) Interview-Assistent, MCP-Tools
|
||||||
|
3. **Gute Fragen an mindnet**
|
||||||
|
1. Beispiel-Queries (Wissensabruf, Entscheidungen, Reflexionen)
|
||||||
|
4. **Neue Inhalte eingeben**
|
||||||
|
1. Notes in Obsidian erstellen
|
||||||
|
2. Typen und Links bewusst setzen (vereinfachte Version aus D)
|
||||||
|
5. **Ergebnisse interpretieren**
|
||||||
|
1. Was bedeutet ein Treffer-Set?
|
||||||
|
2. Wie sind Scores zu lesen? (nur Ist-Stand, Explanation Layer als Ausblick)
|
||||||
|
6. **Feedback & Lernen**
|
||||||
|
1. Manuelles Feedback (gut/schlecht) – Roadmap WP04c/08
|
||||||
|
|
||||||
|
#### Building Blocks
|
||||||
|
|
||||||
|
- Programmplan – Vision & Use-Cases. :contentReference[oaicite:76]{index=76}
|
||||||
|
- Knowledge Design – Autorensicht (stark vereinfacht). :contentReference[oaicite:77]{index=77}
|
||||||
|
- Retriever-Dokumente – Scoring & Interpretation. :contentReference[oaicite:78]{index=78}
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### I) `mindnet_appendices_v2.2.md`
|
||||||
|
|
||||||
|
#### Zweck & Zielgruppe
|
||||||
|
- Referenzen, Tabellen, technische Details, die Hauptdokumente nicht überfrachten sollen.
|
||||||
|
|
||||||
|
#### Geplantes Inhaltsverzeichnis
|
||||||
|
|
||||||
|
1. **Typenreferenz (Auszug aus `types.yaml`)**
|
||||||
|
- Tabellenform: Typ, chunk_profile, edge_defaults, retriever_weight
|
||||||
|
2. **Edge-Typen & Bedeutungen**
|
||||||
|
- belongs_to, references, depends_on, similar_to, related_to, next, prev, …
|
||||||
|
3. **Datenmodelle (JSON-Skizzen)**
|
||||||
|
- Note, Chunk, Edge-Payload (aktuell implementierter Stand)
|
||||||
|
4. **Relevante ENV-Variablen & Konfigurationen**
|
||||||
|
- Hash-Settings, COLLECTION_PREFIX, MINDNET_TYPES_FILE, MINDNET_RETRIEVER_CONFIG etc.
|
||||||
|
5. **WP-Übersicht & Status**
|
||||||
|
- kompakte Tabelle aller WPs mit Status (🟢/🟡) und Verweisen auf relevante Dokumente.
|
||||||
|
6. **Historische Dokumente**
|
||||||
|
- Verweis auf alte Versionen (`mindnet_functional_architecture.md`, ältere Playbooks), falls diese nicht vollständig eingearbeitet werden.
|
||||||
|
|
||||||
|
#### Building Blocks
|
||||||
|
|
||||||
|
- `TYPE_REGISTRY_MANUAL.md` – Typen-Referenz. :contentReference[oaicite:84]{index=84}
|
||||||
|
- `chunking_strategy.md` – JSON-Beispiele. :contentReference[oaicite:85]{index=85}
|
||||||
|
- `mindnet_technical_architecture.md` – Felder & Prioritäten. :contentReference[oaicite:86]{index=86}
|
||||||
|
- Programmplan – WP-Tabellen.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Bearbeitungsreihenfolge (Empfehlung)
|
||||||
|
|
||||||
|
Aus Sicht der Informationssicherung und Konsistenz ist folgende Reihenfolge sinnvoll:
|
||||||
|
|
||||||
|
1. **C – `mindnet_technical_architecture_v2.2.md`**
|
||||||
|
- Begründung:
|
||||||
|
- bildet den **aktuellen implementierten Stand** von WP02–WP04a am präzisesten ab,
|
||||||
|
- ist stark an konkrete Felder, Collections und Skripte gebunden (hier ist der Ist-Stand am eindeutigsten belegbar),
|
||||||
|
- ist die Grundlage für Developer Guide, Playbook und Admin Guide.
|
||||||
|
|
||||||
|
2. **E – `mindnet_pipeline_playbook_v2.2.md`**
|
||||||
|
- Konsolidiert Handbuch + Implementation-Playbook + WP04-Dokumente.
|
||||||
|
|
||||||
|
3. **D – `mindnet_knowledge_design_manual_v2.2.md`**
|
||||||
|
- Stellt sicher, dass das Wissensdesign stabil dokumentiert ist, bevor Overview/User Guide entstehen.
|
||||||
|
|
||||||
|
4. **A – `mindnet_overview_v2.2.md`**
|
||||||
|
- Kann sich dann sauber auf die finalisierte fachliche/technische Sicht stützen.
|
||||||
|
|
||||||
|
5. **F, G, H, I**
|
||||||
|
- Developer/Admin/User Guides & Appendices, basierend auf den konsolidierten Kern-Dokumenten.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Nächster konkreter Schritt
|
||||||
|
|
||||||
|
Als nächstes finalisieren wir gemäß dieser Reihenfolge das Dokument:
|
||||||
|
|
||||||
|
> **C – `mindnet_technical_architecture_v2.2.md`**
|
||||||
|
|
||||||
|
Dabei gehen wir wie folgt vor:
|
||||||
|
|
||||||
|
1. Bestehendes `mindnet_technical_architecture.md` **vollständig** als Basis übernehmen. :contentReference[oaicite:89]{index=89}
|
||||||
|
2. Fehlende Details aus `chunking_strategy.md`, `Handbuch.md`, `TYPE_REGISTRY_MANUAL.md` und `wp04_retriever_scoring.md` integrieren (ohne Informationsverlust).
|
||||||
|
3. Ist-Stand vs. Roadmap klar kennzeichnen (WP04b–08, WP05–07).
|
||||||
|
|
||||||
|
Dieses Vorgehen hält die technische Wahrheit konsistent und liefert eine stabile Basis für alle nachfolgenden Dokumente.
|
||||||
@@ -0,0 +1,565 @@
|
|||||||
|
# mindnet v2.2 — Programmplan
|
||||||
|
**Version:** 2.3.1 (Post-WP06 Decision Engine)
|
||||||
|
**Stand:** 2025-12-09
|
||||||
|
**Status:** Aktiv
|
||||||
|
|
||||||
|
---
|
||||||
|
- [mindnet v2.2 — Programmplan](#mindnet-v22--programmplan)
|
||||||
|
- [1. Programmauftrag](#1-programmauftrag)
|
||||||
|
- [2. Vision](#2-vision)
|
||||||
|
- [3. Programmziele](#3-programmziele)
|
||||||
|
- [3.1 Kurzfristig (Abgeschlossen / Laufend)](#31-kurzfristig-abgeschlossen--laufend)
|
||||||
|
- [3.2 Mittelfristig (Nächste Schritte)](#32-mittelfristig-nächste-schritte)
|
||||||
|
- [3.3 Langfristig](#33-langfristig)
|
||||||
|
- [4. Architekturprinzipien](#4-architekturprinzipien)
|
||||||
|
- [5. Programmstruktur (Phasenmodell)](#5-programmstruktur-phasenmodell)
|
||||||
|
- [6. Workpackages – detaillierte Übersicht](#6-workpackages--detaillierte-übersicht)
|
||||||
|
- [Legende Aufwand / Komplexität](#legende-aufwand--komplexität)
|
||||||
|
- [WP-01 – Wissensdesign (abgeschlossen)](#wp-01--wissensdesign-abgeschlossen)
|
||||||
|
- [WP-02 – Chunking \& Hash-Strategie (abgeschlossen)](#wp-02--chunking--hash-strategie-abgeschlossen)
|
||||||
|
- [WP-03 – Import-Pipeline \& Edge-System v2 (abgeschlossen)](#wp-03--import-pipeline--edge-system-v2-abgeschlossen)
|
||||||
|
- [WP-04a – Retriever \& Graph-Scoring (abgeschlossen)](#wp-04a--retriever--graph-scoring-abgeschlossen)
|
||||||
|
- [WP-04b – Explanation Layer ("Why-Layer") (abgeschlossen)](#wp-04b--explanation-layer-why-layer-abgeschlossen)
|
||||||
|
- [WP-04c – Feedback Logging \& Bewertungsdaten (abgeschlossen)](#wp-04c--feedback-logging--bewertungsdaten-abgeschlossen)
|
||||||
|
- [WP-05 – Persönlichkeitsmodell \& RAG-Chat (abgeschlossen)](#wp-05--persönlichkeitsmodell--rag-chat-abgeschlossen)
|
||||||
|
- [WP-05b – Advanced Chat (Optional)](#wp-05b--advanced-chat-optional)
|
||||||
|
- [WP-06 – Decision Engine \& Hybrid Router (abgeschlossen)](#wp-06--decision-engine--hybrid-router-abgeschlossen)
|
||||||
|
- [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-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)
|
||||||
|
- [WP-14 – Review / Refactoring / Dokumentation (geplant)](#wp-14--review--refactoring--dokumentation-geplant)
|
||||||
|
- [7. Abhängigkeiten (vereinfacht, aktualisiert)](#7-abhängigkeiten-vereinfacht-aktualisiert)
|
||||||
|
- [8. Laufzeit- \& Komplexitätsindikatoren (aktualisiert)](#8-laufzeit---komplexitätsindikatoren-aktualisiert)
|
||||||
|
- [9. Programmfortschritt (Ampel, aktualisiert)](#9-programmfortschritt-ampel-aktualisiert)
|
||||||
|
- [10. Governance \& Versionierung](#10-governance--versionierung)
|
||||||
|
- [11. Executive Summary](#11-executive-summary)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Programmauftrag
|
||||||
|
|
||||||
|
mindnet v2.2 entwickelt ein persönliches, wachsendes KI-Gedächtnis, das:
|
||||||
|
|
||||||
|
- Wissen, Erfahrungen, Werte und Entscheidungen speichert,
|
||||||
|
- diese Informationen semantisch verknüpft und rekonstruierbar macht,
|
||||||
|
- einen KI-Zwilling aufbaut, der ähnlich argumentiert, entscheidet und reflektiert wie du,
|
||||||
|
- über mehrere Kanäle gefüttert wird:
|
||||||
|
- Obsidian-Markdown (primäre Quelle),
|
||||||
|
- Chat-basierter Agent (Decision Engine & RAG-Chat aktiv),
|
||||||
|
- später: Interview-Assistent (strukturierte Dialogerfassung),
|
||||||
|
- automatisch neue Zusammenhänge erkennt und vernetzt (Edges, Typen, Hinweise),
|
||||||
|
- sich durch Rückmeldungen (Feedback) selbst verbessert (Self-Tuning).
|
||||||
|
|
||||||
|
Langfristig soll mindnet als **digitales Gegenüber** funktionieren, das:
|
||||||
|
|
||||||
|
- dich versteht,
|
||||||
|
- deine Denkweise reflektiert,
|
||||||
|
- deine Werte kennt und verwendet,
|
||||||
|
- Entscheidungen begründen kann („Warum?“),
|
||||||
|
- Erinnerungen einordnet,
|
||||||
|
- und für deine Nachkommen als dialogfähiger Gesprächspartner zur Verfügung steht.
|
||||||
|
|
||||||
|
mindnet ist **kein statisches Wissensarchiv**, sondern ein **lebendes, lernendes Gedächtnismodell** mit Fokus auf:
|
||||||
|
|
||||||
|
- persönliche Perspektive,
|
||||||
|
- erklärbare Begründungspfade (Why-Layer),
|
||||||
|
- kontinuierliche Erweiterbarkeit,
|
||||||
|
- robuste technische Basis (lokal, nachvollziehbar, versioniert).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Vision
|
||||||
|
|
||||||
|
> „Ein persönliches semantisches Gedächtnis, das mit mir wächst, meine Persönlichkeit spiegelt und mir als intelligenter, erklärbarer, lernender Begleiter dient.“
|
||||||
|
|
||||||
|
Kernprinzipien der Vision:
|
||||||
|
|
||||||
|
- **Erklärbarkeit:**
|
||||||
|
Jede Antwort muss über Edges, Scores, Werte-Bezüge und Herkunftsnotizen begründbar sein. Das System kann Entscheidungen auf zugrundeliegende `[DECISION]`-Notizen zurückführen.
|
||||||
|
|
||||||
|
- **Wachstum:**
|
||||||
|
Das System arbeitet von Anfang an mit unvollständigen Daten, kann aber schrittweise dichter werden, ohne dass alte Notizen massenhaft manuell angepasst werden müssen.
|
||||||
|
|
||||||
|
- **Flexibilität (Late Binding):**
|
||||||
|
Semantik wird überwiegend in Konfiguration (z. B. `types.yaml`, `prompts.yaml`, `decision_engine.yaml`, Policies) festgelegt. Die Persönlichkeit entsteht durch das Config-Design, nicht durch Hardcoding.
|
||||||
|
|
||||||
|
- **Autonomie & Self-Healing:**
|
||||||
|
mindnet schlägt fehlende Typen, Relationen und Edges vor (z. B. aus Inline-Relationen, Edge-Defaults, Ähnlichkeitsbeziehungen) und baut damit einen „self-healing graph“ auf.
|
||||||
|
|
||||||
|
- **Lernen & Self-Tuning:**
|
||||||
|
Feedback zu Antworten (gut/schlecht, relevant/nicht relevant) fließt in Score-Gewichte, Policies und ggf. Edge-Struktur ein.
|
||||||
|
|
||||||
|
- **Persönlichkeit:**
|
||||||
|
Entscheidungen werden wert- und erfahrungsbasiert begründet; das System agiert als KI-Zwilling durch Nutzung lokaler LLMs (z.B. Phi-3/Mistral) und eines Intent-Routers.
|
||||||
|
|
||||||
|
- **Incremental Growth:**
|
||||||
|
Das System muss mit wenigen, heterogenen Notizen starten und sich fortlaufend verdichten können – ohne Retro-Massenmigrationen im Vault.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Programmziele
|
||||||
|
|
||||||
|
### 3.1 Kurzfristig (Abgeschlossen / Laufend)
|
||||||
|
|
||||||
|
- Automatische Sammlung von Wissen aus Markdown-Vault.
|
||||||
|
- Aufbau eines stabilen Graph-Speichers in Qdrant (`*_notes`, `*_chunks`, `*_edges`).
|
||||||
|
- Semantischer und graphbasierter Retriever (WP-04a abgeschlossen).
|
||||||
|
- **Erklärbarkeit:** Why-Layer liefert Begründungen zu Treffern (WP-04b abgeschlossen).
|
||||||
|
- **Feedback-Loop:** Systematisches Logging von Suche und Bewertung (WP-04c abgeschlossen).
|
||||||
|
- **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).
|
||||||
|
- Automatisierte Erkennung von Beziehungen:
|
||||||
|
- Wikilinks, Inline-Relationen, Callout-Edges, Typ-Defaults.
|
||||||
|
- „Mitwachsendes“ Schema ohne Obsidian-Umstrukturierungen:
|
||||||
|
- Neues Wissen kann sofort erfasst werden,
|
||||||
|
- bestehende Notizen bleiben gültig (Virtual Schema Layer).
|
||||||
|
|
||||||
|
### 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).
|
||||||
|
- 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.
|
||||||
|
|
||||||
|
### 3.3 Langfristig
|
||||||
|
|
||||||
|
- KI-Zwilling, der deinen Stil, deine Werte und deine typische Denkweise repräsentiert.
|
||||||
|
- Weitgehend autonomes Self-Tuning der Wissensstruktur (auf Basis gespeicherter Feedback-Daten & Policies).
|
||||||
|
- Lebenslanges Gedächtnis, das
|
||||||
|
- konsistent bleibt,
|
||||||
|
- wächst,
|
||||||
|
- sich weiterentwickelt,
|
||||||
|
- und deine Geschichte für deine Nachkommen erzählbar und erlebbar macht.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Architekturprinzipien
|
||||||
|
|
||||||
|
Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen:
|
||||||
|
|
||||||
|
1. **Late Binding (späte Semantik)**
|
||||||
|
- Struktur und Interpretation werden in Konfigurationen (z. B. `types.yaml`, `prompts.yaml`, `decision_engine.yaml`) definiert, nicht direkt in den Vault-Dateien.
|
||||||
|
- Die "Persönlichkeit" des Chats ist ein Prompt-Template, kein Code.
|
||||||
|
|
||||||
|
2. **Virtual Schema Layer**
|
||||||
|
- Typen, Regeln, Policies, Edge-Defaults werden im Schema-Layer beschrieben.
|
||||||
|
- Markdown-Dateien benötigen nur minimale, robuste Angaben (Titel, Typ, optionale Properties).
|
||||||
|
|
||||||
|
3. **Self-Healing Graph**
|
||||||
|
- Der Graph wird regelmäßig analysiert (Edges, Centrality, fehlende Links).
|
||||||
|
- Automatisierte Jobs ergänzen fehlende Kanten.
|
||||||
|
|
||||||
|
4. **Deterministische IDs**
|
||||||
|
- Notes, Chunks und Edges erhalten stabile IDs (z. B. UUIDv5).
|
||||||
|
- Der Graph ist jederzeit wiederaufbaubar (Import-Pipeline idempotent).
|
||||||
|
|
||||||
|
5. **Full Explainability & Context Enrichment**
|
||||||
|
- Jeder Score, jede Beziehung muss nachvollziehbar sein.
|
||||||
|
- Dem LLM werden Metadaten (`[DECISION]`, `[PROJECT]`) injiziert, um Halluzinationen zu vermeiden und logische Schlüsse zu ermöglichen.
|
||||||
|
|
||||||
|
6. **Persistence First**
|
||||||
|
- Obsidian bleibt die primäre Quelle der Wahrheit.
|
||||||
|
- mindnet ergänzt, schlägt Änderungen vor, schreibt aber nur kontrolliert.
|
||||||
|
|
||||||
|
7. **Minimalinvasives Schreiben**
|
||||||
|
- Automatische Veränderungen an Markdown-Dateien erfolgen ausschließlich nach expliziter Zustimmung.
|
||||||
|
|
||||||
|
8. **Incremental Growth & Early Value**
|
||||||
|
- Das System muss bereits mit wenigen Notizen und einem kleinen Vault sinnvolle Antworten liefern.
|
||||||
|
- Feedback-Mechanismen werden früh eingeführt.
|
||||||
|
|
||||||
|
9. **Observability & Testbarkeit**
|
||||||
|
- Jeder Importlauf, jede Retriever-Anfrage und jede Policy-Änderung soll prüfbar sein.
|
||||||
|
|
||||||
|
10. **Local First & Privacy**
|
||||||
|
- Nutzung lokaler LLMs (Ollama/Phi-3) für Inference. Keine Daten verlassen den Server.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Programmstruktur (Phasenmodell)
|
||||||
|
|
||||||
|
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 E – Review, Refactoring, Dokumentation
|
||||||
|
|
||||||
|
Alle Workpackages sind einer Phase zugeordnet. WP-01 bis WP-06 sind bereits erfolgreich abgeschlossen.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Workpackages – detaillierte Übersicht
|
||||||
|
|
||||||
|
### Legende Aufwand / Komplexität
|
||||||
|
|
||||||
|
- Aufwand: Niedrig / Mittel / Hoch
|
||||||
|
- Komplexität: Niedrig / Mittel / Hoch
|
||||||
|
|
||||||
|
Die Status-Ampel zeigt den aktuellen Stand gemäß Programmfortschritt.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-01 – Wissensdesign (abgeschlossen)
|
||||||
|
|
||||||
|
**Phase:** A
|
||||||
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Grundlegendes Schema für mindnet festlegen (`knowledge_design.md`), inkl.:
|
||||||
|
- Note-Typen (z. B. `concept`, `experience`, `project`, `decision`, `value`).
|
||||||
|
- Standard-Properties und Grundstruktur von Edges.
|
||||||
|
- Abbildung zentraler Lebens-Bereiche.
|
||||||
|
|
||||||
|
**Erreichte Ergebnisse:**
|
||||||
|
- `knowledge_design.md` und `types.yaml` definieren die Zielarchitektur.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-02 – Chunking & Hash-Strategie (abgeschlossen)
|
||||||
|
|
||||||
|
**Phase:** A
|
||||||
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Festlegen und implementieren einer robusten Chunking-Strategie und einer Hash-Logik zur Änderungserkennung.
|
||||||
|
|
||||||
|
**Erreichte Ergebnisse:**
|
||||||
|
- Implementierte Chunker-Logik mit Overlap.
|
||||||
|
- Stabile Hash-Strategie zur sicheren Änderungserkennung.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-03 – Import-Pipeline & Edge-System v2 (abgeschlossen)
|
||||||
|
|
||||||
|
**Phase:** A/B
|
||||||
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Durchgängige Import-Pipeline von Markdown → Notes/Chunks/Edges in Qdrant mit deterministischen IDs.
|
||||||
|
|
||||||
|
**Erreichte Ergebnisse:**
|
||||||
|
- Vollständige E2E-Import-Pipeline.
|
||||||
|
- Vollständiges Edge-Modell (Strukturkanten, Wikilinks, Inline-Relationen).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-04a – Retriever & Graph-Scoring (abgeschlossen)
|
||||||
|
|
||||||
|
**Phase:** B
|
||||||
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Aufbau eines hybriden Retrievers, der Semantik, Typwissen und Graph-Informationen kombiniert.
|
||||||
|
|
||||||
|
**Erreichte Ergebnisse:**
|
||||||
|
- Hybrides Scoring-Modell (Semantic + Edge + Centrality).
|
||||||
|
- Konfiguration über `retriever.yaml`.
|
||||||
|
- `/query` Endpoint aktiv.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-04b – Explanation Layer ("Why-Layer") (abgeschlossen)
|
||||||
|
|
||||||
|
**Phase:** B
|
||||||
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Treffererklärungen liefern, die verständlich machen, warum ein Ergebnis gewählt wurde.
|
||||||
|
|
||||||
|
**Erreichte Ergebnisse:**
|
||||||
|
- **DTO-Erweiterung:** `QueryHit` enthält `explanation`, `breakdown` und `reason`.
|
||||||
|
- **Logic:** Graph-Adapter unterstützt `incoming_edges` (Reverse Lookup) für Authority-Erklärungen.
|
||||||
|
- **Output:** `/query` Endpoint liefert auf Wunsch (`explain: true`) menschenlesbare Begründungen ("Verweist auf...").
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-04c – Feedback Logging & Bewertungsdaten (abgeschlossen)
|
||||||
|
|
||||||
|
**Phase:** B
|
||||||
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Grundlage für Self-Tuning schaffen durch systematisches Logging.
|
||||||
|
|
||||||
|
**Erreichte Ergebnisse:**
|
||||||
|
- **Data Flywheel:** Logging von Queries und User-Feedback in lokalen JSONL-Dateien.
|
||||||
|
- **Search Log:** Speichert Query + Score-Snapshot in `data/logs/search_history.jsonl`.
|
||||||
|
- **Feedback Log:** Speichert User-Ratings in `data/logs/feedback.jsonl`.
|
||||||
|
- **Traceability:** Durchgängige `query_id` von Request bis Feedback.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-05 – Persönlichkeitsmodell & RAG-Chat (abgeschlossen)
|
||||||
|
|
||||||
|
**Phase:** C
|
||||||
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Aufbau eines RAG-Systems, das in natürlicher Sprache antwortet und Kontext versteht.
|
||||||
|
|
||||||
|
**Erreichte Ergebnisse:**
|
||||||
|
- **Infrastruktur:** Integration von Ollama (Phi-3 Mini) in den Service-Layer.
|
||||||
|
- **Router:** `/chat` Endpoint mit "Hybrid Retrieval Enforcement".
|
||||||
|
- **Context Enrichment:** Injection von Metadaten (`[TYPE]`, `[SCORE]`) in den Prompt, damit kleine Modelle (SLMs) komplexe Zusammenhänge ("Warum?") verstehen.
|
||||||
|
- **Config:** `prompts.yaml` steuert System-Prompt und RAG-Template.
|
||||||
|
|
||||||
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Mittel
|
||||||
|
- Komplexität: Mittel
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-05b – Advanced Chat (Optional)
|
||||||
|
|
||||||
|
**Phase:** C
|
||||||
|
**Status:** ⚪ optional
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Erweiterung des Chats um Gedächtnis (History) und einfache Tools.
|
||||||
|
|
||||||
|
**Umfang:**
|
||||||
|
- Implementierung von `ChatHistory` (vergangene Nachrichten in den Kontext).
|
||||||
|
- Einfache Tool-Nutzung (z.B. "Suche in Web").
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-06 – Decision Engine & Hybrid Router (abgeschlossen)
|
||||||
|
|
||||||
|
**Phase:** C
|
||||||
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Transformation vom reinen Wissens-Abrufer zum strategischen Entscheidungspartner durch Intent-Erkennung.
|
||||||
|
|
||||||
|
**Erreichte Ergebnisse:**
|
||||||
|
- **Hybrid Intent Router:** Kombination aus schnellem Keyword-Matching und intelligentem LLM-Fallback zur Erkennung der Absicht (`DECISION`, `EMPATHY`, `FACT`, `CODING`).
|
||||||
|
- **Strategic Retrieval:** Gezieltes Nachladen von Werten (`value`), Zielen (`goal`) oder Erfahrungen (`experience`) basierend auf dem Intent.
|
||||||
|
- **Multi-Persona:** Dynamische Anpassung des Tonfalls (Berater vs. Spiegel vs. Techniker) durch `prompts.yaml`.
|
||||||
|
- **Late Binding:** Vollständige Konfiguration via `decision_engine.yaml`.
|
||||||
|
- **Robustheit:** Konfigurierbare Timeouts für CPU-Inference.
|
||||||
|
|
||||||
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Mittel
|
||||||
|
- Komplexität: Hoch
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-07 – Interview-Assistent (geplant)
|
||||||
|
|
||||||
|
**Phase:** C
|
||||||
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Niedrig/Mittel
|
||||||
|
- Komplexität: Mittel
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-08 – Self-Tuning v1/v2 (geplant)
|
||||||
|
|
||||||
|
**Phase:** B/C
|
||||||
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Aufbau eines Self-Tuning-Mechanismus, der auf Basis von Feedback-Daten (WP-04c) Vorschläge für Retriever- und Policy-Anpassungen macht.
|
||||||
|
|
||||||
|
**Umfang:**
|
||||||
|
- Auswertung der JSONL-Feedback-Daten.
|
||||||
|
- Regel-basierte Anpassungs-Vorschläge für `retriever.yaml` und Typ-Prioritäten.
|
||||||
|
|
||||||
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Hoch
|
||||||
|
- Komplexität: Hoch
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-09 – Vault-Onboarding & Migration (geplant)
|
||||||
|
|
||||||
|
**Phase:** B
|
||||||
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet integriert werden können – ohne Massenumbau.
|
||||||
|
|
||||||
|
**Umfang:**
|
||||||
|
- Tools zur Analyse des Vault-Status.
|
||||||
|
- Empfehlungen für minimale Anpassungen.
|
||||||
|
|
||||||
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Mittel
|
||||||
|
- Komplexität: Niedrig/Mittel
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-10 – Chat-Interface & Writeback (geplant)
|
||||||
|
|
||||||
|
**Phase:** D
|
||||||
|
**Status:** 🟡 geplant (Priorität B - "Quick Win")
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Hoch (durch Writeback) / Mittel (für reines Frontend)
|
||||||
|
- Komplexität: Hoch
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-11 – Knowledge-Builder & Vernetzungs-Assistent (geplant)
|
||||||
|
|
||||||
|
**Phase:** D
|
||||||
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Assistent, der manuell erstellte oder importierte Notizen analysiert und Vorschläge für Typen, Edges und Einordnung macht.
|
||||||
|
|
||||||
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Hoch
|
||||||
|
- Komplexität: Hoch
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-12 – Knowledge Rewriter (Soft Mode, geplant)
|
||||||
|
|
||||||
|
**Phase:** C/D
|
||||||
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Optionaler Assistent, der vorhandene Notes „aufräumt“, zusammenfasst oder reorganisiert – ausschließlich mit expliziter Freigabe.
|
||||||
|
|
||||||
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Niedrig/Mittel
|
||||||
|
- Komplexität: Mittel
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-13 – MCP-Integration & Agenten-Layer (geplant)
|
||||||
|
|
||||||
|
**Phase:** D
|
||||||
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
mindnet als MCP-Server bereitstellen, damit Agenten/LLMs standardisierte Tools nutzen können.
|
||||||
|
|
||||||
|
**Umfang:**
|
||||||
|
- MCP-Server mit Tools (`mindnet_query`, `mindnet_explain`, etc.).
|
||||||
|
|
||||||
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Mittel
|
||||||
|
- Komplexität: Mittel
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### WP-14 – Review / Refactoring / Dokumentation (geplant)
|
||||||
|
|
||||||
|
**Phase:** E
|
||||||
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
|
**Ziel:**
|
||||||
|
Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritter und Langfrist-Betrieb.
|
||||||
|
|
||||||
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Mittel
|
||||||
|
- Komplexität: Niedrig/Mittel
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Abhängigkeiten (vereinfacht, aktualisiert)
|
||||||
|
|
||||||
|
WP01 → WP02 → WP03 → WP04a
|
||||||
|
WP04a → WP04b → WP04c → WP08
|
||||||
|
WP03 → WP05 → WP06 → WP07
|
||||||
|
WP03 → WP09
|
||||||
|
WP01/WP03 → WP10 → WP11 → WP12
|
||||||
|
WP03/WP04 → WP13
|
||||||
|
Alles → WP14
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Laufzeit- & Komplexitätsindikatoren (aktualisiert)
|
||||||
|
|
||||||
|
| WP | Aufwand | Komplexität |
|
||||||
|
|-------|----------------|------------------|
|
||||||
|
| WP04b | Mittel | Hoch |
|
||||||
|
| WP04c | Mittel | Mittel/Hoch |
|
||||||
|
| WP05 | Mittel | Mittel |
|
||||||
|
| WP06 | Mittel | Hoch |
|
||||||
|
| WP07 | Niedrig/Mittel | Mittel |
|
||||||
|
| WP08 | Hoch | Hoch |
|
||||||
|
| WP09 | Mittel | Niedrig/Mittel |
|
||||||
|
| WP10 | Hoch | Hoch |
|
||||||
|
| WP11 | Hoch | Hoch |
|
||||||
|
| WP12 | Niedrig/Mittel | Mittel |
|
||||||
|
| WP13 | Mittel | Mittel |
|
||||||
|
| WP14 | Mittel | Niedrig/Mittel |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Programmfortschritt (Ampel, aktualisiert)
|
||||||
|
|
||||||
|
| WP | Status |
|
||||||
|
|-------|--------|
|
||||||
|
| WP01 | 🟢 |
|
||||||
|
| WP02 | 🟢 |
|
||||||
|
| WP03 | 🟢 |
|
||||||
|
| WP04a | 🟢 |
|
||||||
|
| WP04b | 🟢 |
|
||||||
|
| WP04c | 🟢 |
|
||||||
|
| WP05 | 🟢 |
|
||||||
|
| WP05b | ⚪ |
|
||||||
|
| WP06 | 🟢 |
|
||||||
|
| WP07 | 🟡 |
|
||||||
|
| WP08 | 🟡 |
|
||||||
|
| WP09 | 🟡 |
|
||||||
|
| WP10 | 🟡 |
|
||||||
|
| WP11 | 🟡 |
|
||||||
|
| WP12 | 🟡 |
|
||||||
|
| WP13 | 🟡 |
|
||||||
|
| WP14 | 🟡 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Governance & Versionierung
|
||||||
|
|
||||||
|
- Versionierung über Gitea (Branches, Tags, Releases).
|
||||||
|
- Feature-Branch Workflow mit "Sync First" Strategie.
|
||||||
|
- Jede wesentliche Änderung an Architektur/Schema erhält einen eigenen Commit.
|
||||||
|
- Jedes Workpackage erhält ein eigenes Chat-Fenster mit dediziertem Prompt (WP-Hand-Over).
|
||||||
|
- Programmleitung verantwortet Konsistenz und Priorisierung.
|
||||||
|
- **Modell-Governance:** Das verwendete LLM (z.B. `phi3:mini`) wird in der `.env` und `config.py` festgeschrieben. Updates erfordern Tests gegen die "Why-Layer" Referenzfragen.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Executive Summary
|
||||||
|
|
||||||
|
mindnet v2.2 ist so aufgesetzt, dass:
|
||||||
|
|
||||||
|
- du **schrittweise** Wissen erfassen kannst (Obsidian + Chat + später Interview-Assistent),
|
||||||
|
- die Struktur **mitwächst**, ohne Retro-Massenarbeit im Vault,
|
||||||
|
- 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,
|
||||||
|
- 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.
|
||||||
|
|
||||||
|
Dieser Programmplan bildet die konsolidierte Grundlage (v2.3.1) für alle weiteren Arbeiten.
|
||||||
@@ -0,0 +1,307 @@
|
|||||||
|
# mindnet v2 — Dokumentationsreview (vollständig & konsolidiert)
|
||||||
|
|
||||||
|
Dieses Dokument fasst alle notwendigen Anpassungen der mindnet-v2 Dokumentation zusammen.
|
||||||
|
Der Fokus liegt ausschließlich auf Aspekten, die durch die aktuellen Arbeiten verändert wurden:
|
||||||
|
|
||||||
|
- neue Edge-Mechanik
|
||||||
|
- neuer Importer
|
||||||
|
- neues Verhalten von note_payload & chunk_payload
|
||||||
|
- Default-Typregeln aus `types.yaml`
|
||||||
|
- Inline- und Callout-Relations
|
||||||
|
- WP04a – Einführung der Retriever-Schicht
|
||||||
|
- neue Diagnose- und Testskripte
|
||||||
|
|
||||||
|
Es handelt sich um eine strukturelle Analyse.
|
||||||
|
Nichts davon überschreibt bestehende Inhalte — es markiert nur, **was angepasst werden muss**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 1) knowledge_design.md
|
||||||
|
## Erforderliche Anpassungen
|
||||||
|
|
||||||
|
### 1.1 Neue Edge-Arten dokumentieren
|
||||||
|
Es müssen vier neue Kategorien beschrieben werden:
|
||||||
|
|
||||||
|
1. **Inline-Edges**
|
||||||
|
|
||||||
|
Beispiel:
|
||||||
|
`[ [rel:depends_on Embeddings 101] ]`
|
||||||
|
(Leerzeichen hier zur Demonstration; im echten Dokument ohne Leerzeichen)
|
||||||
|
|
||||||
|
2. **Callout-Edges**
|
||||||
|
|
||||||
|
> [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]]
|
||||||
|
|
||||||
|
3. **Typbasierte Default-Kanten**
|
||||||
|
Aus `types.yaml` → `edge_defaults`
|
||||||
|
|
||||||
|
4. **Strukturkanten**
|
||||||
|
- belongs_to
|
||||||
|
- next
|
||||||
|
- prev
|
||||||
|
|
||||||
|
### 1.2 Neue Edge-Felder ergänzen
|
||||||
|
Jeder Edge enthält jetzt:
|
||||||
|
|
||||||
|
- `rule_id`
|
||||||
|
- `confidence`
|
||||||
|
- `scope = "chunk"`
|
||||||
|
- deterministischer `edge_id`
|
||||||
|
|
||||||
|
Diese Felder müssen vollständig erklärt werden.
|
||||||
|
|
||||||
|
### 1.3 Chunk-basierte Kanten
|
||||||
|
Neu: **Alle Kanten entstehen ausschließlich zwischen Chunks**, nie zwischen Notes.
|
||||||
|
Notes dienen nur noch als Metadatencontainer.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 2) TYPE_REGISTRY_MANUAL.md
|
||||||
|
## Erforderliche Anpassungen
|
||||||
|
|
||||||
|
### 2.1 Typauflösung dokumentieren
|
||||||
|
Die Regeln sind jetzt:
|
||||||
|
|
||||||
|
- Typ aus Frontmatter → höchste Priorität
|
||||||
|
- Falls nicht gesetzt: Typ aus Dateipfad ableiten
|
||||||
|
- Falls unbekannt: Fallback auf `types.default`
|
||||||
|
- Typ definiert:
|
||||||
|
- retriever_weight
|
||||||
|
- chunk_profile
|
||||||
|
- edge_defaults
|
||||||
|
|
||||||
|
Diese müssen klar dokumentiert werden.
|
||||||
|
|
||||||
|
### 2.2 Neue Fallback-Regeln
|
||||||
|
Wenn Werte fehlen, werden sie ersetzt durch:
|
||||||
|
|
||||||
|
types.default.retriever_weight
|
||||||
|
types.default.chunk_profile
|
||||||
|
types.default.edge_defaults
|
||||||
|
|
||||||
|
### 2.3 Beispiele aktualisieren
|
||||||
|
Alle Beispiele müssen auf die neue Inline-Syntax angepasst werden.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 3) wp04_retriever_scoring.md
|
||||||
|
## Erforderliche Anpassungen
|
||||||
|
|
||||||
|
### 3.1 Neue Scoring-Formel
|
||||||
|
total_score =
|
||||||
|
semantic_weight * semantic_score
|
||||||
|
+ edge_weight * edge_bonus
|
||||||
|
+ centrality_weight * centrality_bonus
|
||||||
|
+ type_weight * retriever_weight
|
||||||
|
|
||||||
|
### 3.2 Bedeutung von `confidence`
|
||||||
|
confidence wirkt multiplikativ bei edge_bonus.
|
||||||
|
Inline > Callout > Default (Standardwerte im Code hinterlegt).
|
||||||
|
|
||||||
|
### 3.3 Pfadbegründungen
|
||||||
|
Der Retriever gibt optional `paths[]` zurück:
|
||||||
|
|
||||||
|
paths: [
|
||||||
|
{
|
||||||
|
"via": "depends_on",
|
||||||
|
"confidence": 0.7,
|
||||||
|
"hops": ["Note A", "Chunk A#01", "Note B"]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
Diese Funktion müssen dokumentiert werden.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 4) mindnet_v2_implementation_playbook.md
|
||||||
|
## Erforderliche Anpassungen
|
||||||
|
|
||||||
|
### 4.1 Neuer Import-Prozess vollständig dokumentieren
|
||||||
|
Der Importer läuft jetzt so:
|
||||||
|
|
||||||
|
1. Markdown lesen
|
||||||
|
2. Frontmatter extrahieren
|
||||||
|
3. Typauflösung via `types.yaml`
|
||||||
|
4. Note-Payload generieren
|
||||||
|
5. Chunking anwenden
|
||||||
|
6. Inline-Kanten finden
|
||||||
|
7. Callout-Kanten finden
|
||||||
|
8. Default-Edges erzeugen
|
||||||
|
9. Strukturkanten erzeugen
|
||||||
|
10. Chunks in Qdrant upserten
|
||||||
|
11. Edges upserten
|
||||||
|
12. Diagnose laufen lassen:
|
||||||
|
|
||||||
|
python3 -m scripts.payload_dryrun
|
||||||
|
python3 -m scripts.edges_full_check
|
||||||
|
|
||||||
|
### 4.2 Erweiterte Testpipeline
|
||||||
|
Neu zu dokumentieren:
|
||||||
|
|
||||||
|
tests.test_edges_all
|
||||||
|
scripts.edges_full_check
|
||||||
|
scripts.payload_dryrun
|
||||||
|
|
||||||
|
Diese Testschritte sind jetzt Standardanforderung nach jeder Änderung.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 5) mindnet_technical_architecture.md
|
||||||
|
## Erforderliche Anpassungen
|
||||||
|
|
||||||
|
### 5.1 Aktualisiertes Schema für Qdrant Collections
|
||||||
|
|
||||||
|
#### Notes:
|
||||||
|
note_id
|
||||||
|
title
|
||||||
|
type
|
||||||
|
fulltext
|
||||||
|
retriever_weight
|
||||||
|
chunk_profile
|
||||||
|
edge_defaults
|
||||||
|
tags
|
||||||
|
updated
|
||||||
|
|
||||||
|
#### Chunks:
|
||||||
|
chunk_id
|
||||||
|
note_id
|
||||||
|
text
|
||||||
|
window
|
||||||
|
ord
|
||||||
|
retriever_weight
|
||||||
|
chunk_profile
|
||||||
|
neighbors_prev
|
||||||
|
neighbors_next
|
||||||
|
|
||||||
|
#### Edges:
|
||||||
|
edge_id
|
||||||
|
source_id
|
||||||
|
target_id
|
||||||
|
kind
|
||||||
|
scope = "chunk"
|
||||||
|
rule_id
|
||||||
|
confidence
|
||||||
|
|
||||||
|
### 5.2 Dokumentation der Edge-Pipeline
|
||||||
|
Neu beschreiben:
|
||||||
|
|
||||||
|
- Inline-Parser
|
||||||
|
- Callout-Parser
|
||||||
|
- Default-Edge-Resolver
|
||||||
|
- Strukturkanten
|
||||||
|
- Normalisierung für Qdrant
|
||||||
|
- deterministische ID-Bildung
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 6) mindnet_functional_architecture.md
|
||||||
|
## Erforderliche Anpassungen
|
||||||
|
|
||||||
|
### 6.1 Inline-Relations – einzig gültige Syntax
|
||||||
|
Nur diese Syntax erzeugt Kanten:
|
||||||
|
|
||||||
|
[[rel:depends_on Embeddings 101]]
|
||||||
|
|
||||||
|
Nicht unterstützt:
|
||||||
|
|
||||||
|
rel:depends_on [[Embeddings 101]]
|
||||||
|
|
||||||
|
Dies muss klar dokumentiert werden.
|
||||||
|
|
||||||
|
### 6.2 Prioritäten der Kantenerzeugung
|
||||||
|
Gültige Reihenfolge:
|
||||||
|
|
||||||
|
1. Inline
|
||||||
|
2. Callout
|
||||||
|
3. Typdefaults
|
||||||
|
4. Strukturkanten
|
||||||
|
|
||||||
|
### 6.3 Relaunch der Chunk-zentrierten Funktionslogik
|
||||||
|
Alle Beispiele müssen angepasst werden.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 7) chunking_strategy.md
|
||||||
|
## Erforderliche Änderungen
|
||||||
|
|
||||||
|
### 7.1 Neues Verhalten der Chunks
|
||||||
|
- `ord` ist jetzt Sortierkriterium
|
||||||
|
- `window` wird über chunk_config erzeugt
|
||||||
|
- Chunkprofile kommen ausschließlich aus `types.yaml`
|
||||||
|
|
||||||
|
### 7.2 Best Practices erneuern
|
||||||
|
Empfehlung:
|
||||||
|
|
||||||
|
- keine manuelle Chunkprofile mehr im Frontmatter setzen
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 8) docs_mindnet_retriever.md
|
||||||
|
## Erforderliche Änderungen
|
||||||
|
|
||||||
|
### 8.1 Neue Ausgabeparameter dokumentieren
|
||||||
|
Retriever liefert jetzt:
|
||||||
|
|
||||||
|
semantic_score
|
||||||
|
edge_bonus
|
||||||
|
centrality_bonus
|
||||||
|
type_score
|
||||||
|
total_score
|
||||||
|
paths[]
|
||||||
|
|
||||||
|
### 8.2 Graph-Expansion
|
||||||
|
Dokumentieren:
|
||||||
|
|
||||||
|
- Seed-Auswahl
|
||||||
|
- Depth-Limit
|
||||||
|
- Edge-Filterung
|
||||||
|
- Wirkung von `confidence` auf edge_bonus
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 9) Handbuch.md
|
||||||
|
## Erforderliche Änderungen
|
||||||
|
|
||||||
|
### 9.1 Neuer Import-Workflow
|
||||||
|
Erläuterung der Parser:
|
||||||
|
|
||||||
|
- Inline-Parser
|
||||||
|
- Callout-Parser
|
||||||
|
- Default-Kanten
|
||||||
|
- Struktur-Kanten
|
||||||
|
|
||||||
|
### 9.2 Best Practices
|
||||||
|
Ergänzen:
|
||||||
|
|
||||||
|
- Typenpflege erfolgt nur in `types.yaml`
|
||||||
|
- Tests immer nach Änderungen ausführen
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Gesamtübersicht der notwendigen Anpassungen
|
||||||
|
|
||||||
|
| Dokument | Anpassungsbedarf |
|
||||||
|
|---------|------------------|
|
||||||
|
| knowledge_design.md | neue Edge-Arten, Felder, Chunk-Edges |
|
||||||
|
| TYPE_REGISTRY_MANUAL.md | Typauflösung, neue Felder, neue Fallbacks |
|
||||||
|
| wp04_retriever_scoring.md | neue Score-Formel, Pfade, confidence |
|
||||||
|
| implementation_playbook.md | neuer Importprozess, Tests |
|
||||||
|
| technical_architecture.md | aktualisierte Schemas |
|
||||||
|
| functional_architecture.md | Syntax + Prioritäten |
|
||||||
|
| chunking_strategy.md | ord, window, neue Profile |
|
||||||
|
| docs_mindnet_retriever.md | neue API-Parameter |
|
||||||
|
| Handbuch.md | Parser + Best Practices |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Empfehlung zur Umsetzung
|
||||||
|
1. Dieses Review-Dokument als Master-Referenz verwenden.
|
||||||
|
2. Jedes Dokument strikt nur an den beschriebenen Stellen anpassen.
|
||||||
|
3. Überprüfen, ob Wann/Wo Typen, Kanten und Parser erklärt werden.
|
||||||
|
4. Nach jeder Anpassung Testlauf:
|
||||||
|
|
||||||
|
python3 -m scripts.payload_dryrun
|
||||||
|
python3 -m scripts.edges_full_check
|
||||||
|
|
||||||
|
5. Danach Playbook + Programmplan updaten.
|
||||||
|
|
||||||
@@ -0,0 +1,322 @@
|
|||||||
|
# mindnet – Änderungs- und Ergänzungsleitfaden für bestehende Dokumentation
|
||||||
|
# (Stand: Tag Wp04a-Retriever_final)
|
||||||
|
|
||||||
|
Dieser Leitfaden listet **alle notwendigen Änderungen und Ergänzungen** für die
|
||||||
|
bestehenden Dokumente auf. Er umfasst ausschließlich Inhalte, die durch die
|
||||||
|
tatsächliche Implementierung von WP-04a (Retriever, Hybrid Scoring, Graph-Integration,
|
||||||
|
retriever.yaml, Explainability-Vorbereitung, Centrality, Edge-Bonus, Query-API)
|
||||||
|
betroffen sind.
|
||||||
|
|
||||||
|
Er dient dazu, dass ein anderer Chat alle Dokumente vollständig und korrekt
|
||||||
|
überarbeiten kann, ohne Interpretationsspielraum oder fehlende Informationen.
|
||||||
|
|
||||||
|
|
||||||
|
============================================================
|
||||||
|
# 1. Änderungen für: knowledge_design.md
|
||||||
|
============================================================
|
||||||
|
|
||||||
|
## 1.1 Ergänzen: Rolle von retriever_weight pro Note-Type
|
||||||
|
Die Implementierung nutzt `retriever_weight`, das im Importer aus `types.yaml`
|
||||||
|
pro Note-Type übernommen und auf *Chunk-Ebene* vererbt wird.
|
||||||
|
|
||||||
|
**Ergänzen:**
|
||||||
|
- Erklärung, dass `retriever_weight` ein konzeptionelles Typ-Attribut ist,
|
||||||
|
das im hybriden Scoring als Multiplikator wirkt.
|
||||||
|
- Klarstellung, dass `retriever_weight` *nicht* durch Markdown-Frontmatter
|
||||||
|
überschrieben werden muss.
|
||||||
|
- Dokumentation, dass Qdrant-Payload dieses Feld für Notes und Chunks enthält.
|
||||||
|
|
||||||
|
## 1.2 Ergänzen: Edge-Typen, die im Retriever genutzt werden
|
||||||
|
Der Retriever unterstützt aktuell:
|
||||||
|
- `references`
|
||||||
|
- `related_to`
|
||||||
|
- `depends_on`
|
||||||
|
- `similar_to`
|
||||||
|
- `belongs_to`
|
||||||
|
- sowie generierte Strukturkanten `next` / `prev`.
|
||||||
|
|
||||||
|
**Ergänzen:**
|
||||||
|
- Welche Edges für den Graph-Bonus ausgewertet werden.
|
||||||
|
- Wie `confidence` aus mindnet_edges genutzt wird.
|
||||||
|
|
||||||
|
## 1.3 Ergänzen: Definition des lokalen Subgraphen
|
||||||
|
Die reale Retrieval-Logik nutzt:
|
||||||
|
- Seed-Notes (aus semantisch Top-K)
|
||||||
|
- Expansionstiefe `depth`
|
||||||
|
- Edge-Typ-Filter
|
||||||
|
- Bonusberechnung pro Knoten
|
||||||
|
|
||||||
|
Dies ist im ursprünglichen Dokument nicht beschrieben und muss hinzugefügt werden.
|
||||||
|
|
||||||
|
============================================================
|
||||||
|
# 2. Änderungen für: chunking_strategy.md
|
||||||
|
============================================================
|
||||||
|
|
||||||
|
## 2.1 Ergänzen: Chunk-Payload-Felder, die der Retriever nutzt
|
||||||
|
Die aktuelle Strategy beschreibt Chunks korrekt, es fehlt jedoch:
|
||||||
|
|
||||||
|
**Ergänzen:**
|
||||||
|
- `retriever_weight` (vererbt vom Note-Type)
|
||||||
|
- `chunk_profile` (aktuell ungenutzt im Retriever, aber Teil der Payload)
|
||||||
|
- Hinweise, dass der Retriever nur aus *Chunks* semantische Seeds bildet,
|
||||||
|
das Ranking aber auf *Notes* aggregiert wird.
|
||||||
|
|
||||||
|
## 2.2 Ergänzen: Section/Window-Felder und ihre Relevanz
|
||||||
|
Die Felder existieren im Qdrant, werden aber im retriever.yaml nicht verändert.
|
||||||
|
|
||||||
|
**Hinweis ergänzen:**
|
||||||
|
- Der Retriever nutzt aktuell `text` und `window`; kein Einfluss der Abschnittslogik.
|
||||||
|
|
||||||
|
|
||||||
|
============================================================
|
||||||
|
# 3. Änderungen für: TYPE_REGISTRY_MANUAL.md
|
||||||
|
============================================================
|
||||||
|
|
||||||
|
Dieses Dokument muss **aktualisiert** werden, da WP-04a folgende Mechanismen nutzt:
|
||||||
|
|
||||||
|
## 3.1 Ergänzen: Bedeutung von retriever_weight
|
||||||
|
- Definition als quantitatives Typ-Merkmal.
|
||||||
|
- Erklärung, dass es in Qdrant gespeichert wird.
|
||||||
|
- Erklärung des Einflusses auf Semantikscore:
|
||||||
|
- Formel:
|
||||||
|
|
||||||
|
final_semantic = semantic_score * retriever_weight
|
||||||
|
|
||||||
|
- Hinweis, dass in future WP-08 das Gewicht durch Feedback lernbar wird.
|
||||||
|
|
||||||
|
## 3.2 Ergänzen: Neue Edge-Typen und ihre Standard-Konfiguration
|
||||||
|
- `similar_to`
|
||||||
|
- `belongs_to`
|
||||||
|
- Strukturkanten `next` / `prev`
|
||||||
|
|
||||||
|
Diese sind im Importer bereits aktiv, aber nicht ausreichend dokumentiert.
|
||||||
|
|
||||||
|
## 3.3 Ergänzen: Edge-Konfidenzen
|
||||||
|
Die automatische Edge-Ableitung generiert `confidence`.
|
||||||
|
Retriever nutzt diesen Wert linear im Edge-Bonus.
|
||||||
|
|
||||||
|
**Dokumentation muss ergänzt werden.**
|
||||||
|
|
||||||
|
|
||||||
|
============================================================
|
||||||
|
# 4. Änderungen für: docs_mindnet_retriever.md
|
||||||
|
============================================================
|
||||||
|
|
||||||
|
Dieses Dokument ist am stärksten betroffen und muss auf den Stand der tatsächlichen
|
||||||
|
Implementierung aktualisiert werden.
|
||||||
|
|
||||||
|
## 4.1 Aktualisieren: Gesamtscoring-Formel
|
||||||
|
Bisher: Semantik + einfache Typgewichtung.
|
||||||
|
|
||||||
|
Neu implementiert:
|
||||||
|
|
||||||
|
total_score =
|
||||||
|
semantic_weight * semantic_score
|
||||||
|
+ edge_weight * edge_bonus
|
||||||
|
+ centrality_weight * centrality_bonus
|
||||||
|
|
||||||
|
Diese Formel muss vollständig dokumentiert werden.
|
||||||
|
|
||||||
|
## 4.2 Aktualisieren: Einführung retriever.yaml
|
||||||
|
Dokumentation benötigt:
|
||||||
|
|
||||||
|
- Speicherort: `app/config/retriever.yaml`
|
||||||
|
- Default-Werte
|
||||||
|
- Abschnittsweise Beschreibung:
|
||||||
|
- semantic_weight
|
||||||
|
- edge_weight
|
||||||
|
- centrality_weight
|
||||||
|
- Hinweis: Änderungen wirken ohne Codeänderung.
|
||||||
|
|
||||||
|
## 4.3 Ergänzen: Beschreibung Graph-Expansion
|
||||||
|
Der Retriever nutzt:
|
||||||
|
|
||||||
|
- Expand-depth (default 1)
|
||||||
|
- Edge-Typ-Filter
|
||||||
|
- Aggregation pro Node
|
||||||
|
- Bonus-Skalierung
|
||||||
|
|
||||||
|
Diese Logik ist neu und muss detailliert erklärt werden.
|
||||||
|
|
||||||
|
## 4.4 Ergänzen: Beschreibung centrality_bonus
|
||||||
|
Aktuell:
|
||||||
|
- proportionale Verteilung anhand Knotendichte
|
||||||
|
- Normalisierung über lokales Subgraph-Maß
|
||||||
|
|
||||||
|
Dokumentation muss Minimum enthalten:
|
||||||
|
- wie centrality gewichtet wird
|
||||||
|
- welche Grenze existieren
|
||||||
|
|
||||||
|
## 4.5 Ergänzen: Explainability-Schnittstelle (WP-04b Vorbereitung)
|
||||||
|
Die Implementierung erzeugt intern:
|
||||||
|
- edge_bonus pro Node
|
||||||
|
- centrality_bonus pro Node
|
||||||
|
- Liste der Edges, die beteiligt waren
|
||||||
|
|
||||||
|
Diese Werte sind abrufbar und müssen dokumentiert werden.
|
||||||
|
|
||||||
|
## 4.6 Ergänzen: Fehlertoleranzen & Timeout (Health Check)
|
||||||
|
Der Retriever kann:
|
||||||
|
- Fallback auf Vektor-Suche (pure semantic)
|
||||||
|
- Fallback bei fehlendem expand
|
||||||
|
|
||||||
|
Diese Sicherheitsmechanismen müssen dokumentiert werden.
|
||||||
|
|
||||||
|
|
||||||
|
============================================================
|
||||||
|
# 5. Änderungen für: mindnet_technical_architecture.md
|
||||||
|
============================================================
|
||||||
|
|
||||||
|
## 5.1 Ergänzen: Komponentenübersicht Retrieval-Layer
|
||||||
|
Eine neue Abbildung oder Abschnitt muss hinzu:
|
||||||
|
|
||||||
|
- QueryRequest-Parsing
|
||||||
|
- Embedding-Lookup oder Vector-Passthrough
|
||||||
|
- Semantic Seed Search (Qdrant)
|
||||||
|
- Graph-Expansion (mindnet_edges)
|
||||||
|
- Node-/Note-Aggregation
|
||||||
|
- Score-Combination
|
||||||
|
- Response-Ausgabe via FastAPI
|
||||||
|
|
||||||
|
## 5.2 Ergänzen: Datenstruktur mindnet_edges
|
||||||
|
Vor WP-04 nicht vollständig dokumentiert.
|
||||||
|
|
||||||
|
Benötigt:
|
||||||
|
|
||||||
|
- Felder:
|
||||||
|
- edge_id
|
||||||
|
- kind
|
||||||
|
- source_id
|
||||||
|
- target_id
|
||||||
|
- confidence
|
||||||
|
- rule_id
|
||||||
|
- Wie Edges im Retriever ausgewertet werden.
|
||||||
|
|
||||||
|
## 5.3 Ergänzen: retriever.yaml als Konfigurationsquelle
|
||||||
|
Architekturdiagramm muss updated werden:
|
||||||
|
- Retriever nutzt YAML
|
||||||
|
- Keine Hardcodierung im Python
|
||||||
|
|
||||||
|
## 5.4 Ergänzen: Health Check Script
|
||||||
|
Technischer Abschnitt muss dokumentieren:
|
||||||
|
|
||||||
|
- health_check_mindnet.py
|
||||||
|
- Semantik:
|
||||||
|
- semantic query
|
||||||
|
- hybrid query
|
||||||
|
- Fehlercodes
|
||||||
|
|
||||||
|
|
||||||
|
============================================================
|
||||||
|
# 6. Änderungen für: mindnet_functional_architecture.md
|
||||||
|
============================================================
|
||||||
|
|
||||||
|
## 6.1 Ergänzen: Funktionale Rolle des Retrievers
|
||||||
|
Retriever ist jetzt:
|
||||||
|
|
||||||
|
- Teil des Functional Layers
|
||||||
|
- Grundlage für Agenten / Decision Engine
|
||||||
|
- Hauptquelle für Begründungen
|
||||||
|
|
||||||
|
## 6.2 Ergänzen: Einbindung des Explainability-Layers
|
||||||
|
Funktional gehört dies zwischen:
|
||||||
|
- Retriever
|
||||||
|
- Antwortgenerierung (LLM)
|
||||||
|
|
||||||
|
Der Explainability-Layer formuliert Gründe:
|
||||||
|
- Welche Edges?
|
||||||
|
- Welche Scores?
|
||||||
|
- Warum diese Note?
|
||||||
|
|
||||||
|
## 6.3 Ergänzen: Self-Tuning als neuen Funktionsblock (WP-08)
|
||||||
|
Muss aufgenommen werden:
|
||||||
|
|
||||||
|
- Logging von Feedback
|
||||||
|
- Bewertung
|
||||||
|
- Tuning der retriever.yaml
|
||||||
|
- Human-in-the-loop Freigabe
|
||||||
|
|
||||||
|
|
||||||
|
============================================================
|
||||||
|
# 7. Änderungen für: wp04_retriever_scoring.md
|
||||||
|
============================================================
|
||||||
|
|
||||||
|
Dieses Dokument ist **direkt WP-04** und muss am stärksten überarbeitet werden.
|
||||||
|
|
||||||
|
## 7.1 Aktualisieren: Finale Scoring-Formel
|
||||||
|
Die Formel muss exakt so dokumentiert werden, wie inzwischen implementiert.
|
||||||
|
|
||||||
|
## 7.2 Ergänzen: Bonusberechnung
|
||||||
|
Die bisherige Planung wurde implementiert, aber der Text muss aktualisiert werden:
|
||||||
|
|
||||||
|
- Bonusberechnung je Edge
|
||||||
|
- confidence-Einfluss
|
||||||
|
- Node-Aggregation
|
||||||
|
- Note-Aggregation
|
||||||
|
|
||||||
|
## 7.3 Ergänzen: Centrality
|
||||||
|
Dokument ist zu ergänzen um:
|
||||||
|
|
||||||
|
- Definition
|
||||||
|
- Berechnung
|
||||||
|
- Normalisierung
|
||||||
|
- Gewichtung über retriever.yaml
|
||||||
|
|
||||||
|
## 7.4 Ergänzen: Teststrategie
|
||||||
|
Die finale Testbasis muss dokumentiert werden:
|
||||||
|
|
||||||
|
- Unit-Tests
|
||||||
|
- Hybrid-Tests
|
||||||
|
- API-Tests
|
||||||
|
- Smoke-Test
|
||||||
|
- Diagnose-Skripte
|
||||||
|
|
||||||
|
## 7.5 Ergänzen: Einschränkungen & Offene Punkte
|
||||||
|
Hinweis für WP-04b:
|
||||||
|
- Explainability fehlt noch
|
||||||
|
- Edge-Type Weights noch nicht implementiert
|
||||||
|
- Self-Tuning in WP-08
|
||||||
|
|
||||||
|
|
||||||
|
============================================================
|
||||||
|
# 8. Änderungen für: mindnet_v2_implementation_playbook.md
|
||||||
|
============================================================
|
||||||
|
|
||||||
|
## 8.1 Ergänzen: Arbeitsablauf mit Retriever
|
||||||
|
Einrichtung, Nutzung und Test sollte ergänzt werden:
|
||||||
|
|
||||||
|
- Starten von FastAPI
|
||||||
|
- Testen des Retrievers via health_check
|
||||||
|
- Import-Workflow (neue Vaults → Qdrant → Retriever)
|
||||||
|
|
||||||
|
## 8.2 Ergänzen: Konfigurationsverwaltung
|
||||||
|
Einbindung in Gitea-Workflows:
|
||||||
|
- retriever.yaml versionieren
|
||||||
|
- Tags/Branches für Funktionsstände setzen
|
||||||
|
|
||||||
|
## 8.3 Ergänzen: Self-Tuning-Prozess (nur Rahmen)
|
||||||
|
Der Playbook-Abschnitt soll die späteren Mechanismen vorbeschreiben.
|
||||||
|
|
||||||
|
|
||||||
|
============================================================
|
||||||
|
# 9. Änderungen für: Handbuch.md
|
||||||
|
============================================================
|
||||||
|
|
||||||
|
## 9.1 Ergänzen: Einfache Erklärung des Retrievers
|
||||||
|
Das Handbuch benötigt eine verständliche, nicht-technische Beschreibung:
|
||||||
|
|
||||||
|
- Was macht der Retriever?
|
||||||
|
- Warum kommt ein Ergebnis zustande?
|
||||||
|
- Welche Rolle spielen Edges?
|
||||||
|
- Wie kann der Nutzer die Gewichtung beeinflussen (YAML)?
|
||||||
|
|
||||||
|
## 9.2 Ergänzen: Troubleshooting
|
||||||
|
Aufnehmen:
|
||||||
|
- „Ergebnisse wirken unpassend“ → Prüfe retriever.yaml
|
||||||
|
- „Edge-Bonus fehlt“ → Prüfe mindnet_edges
|
||||||
|
- health_check-Skript nutzen
|
||||||
|
|
||||||
|
## 9.3 Ergänzen: API-Nutzung für Endanwender
|
||||||
|
Einfacher Abschnitt:
|
||||||
|
- Wie man `/query` testet
|
||||||
|
- Beispiele für semantic & hybrid queries
|
||||||
@@ -33,3 +33,7 @@ python3 scripts/import_markdown.py --vault /path/to/Obsidian
|
|||||||
- `POST /qdrant/query` → semantic search over chunks with optional filters
|
- `POST /qdrant/query` → semantic search over chunks with optional filters
|
||||||
|
|
||||||
See `scripts/quick_test.sh` for a runnable example.
|
See `scripts/quick_test.sh` for a runnable example.
|
||||||
|
|
||||||
|
>Anmerkung:
|
||||||
|
Diese Datei ist veraltet
|
||||||
|
|
||||||
+16
-10
@@ -1,17 +1,11 @@
|
|||||||
"""
|
"""
|
||||||
app/config.py — zentrale Konfiguration (ENV → Settings)
|
app/config.py — zentrale Konfiguration
|
||||||
|
Version: 0.4.0 (WP-06 Complete)
|
||||||
Version:
|
|
||||||
0.2.0 (WP-04: Retriever-Gewichte & Defaults ergänzt; keine Verhaltensänderung für bestehende Nutzung)
|
|
||||||
Stand:
|
|
||||||
2025-10-06
|
|
||||||
Hinweis:
|
|
||||||
Bestehende Attribute bleiben erhalten; neue WP-04 Felder sind optional.
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
import os
|
import os
|
||||||
from functools import lru_cache
|
from functools import lru_cache
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
class Settings:
|
class Settings:
|
||||||
# Qdrant
|
# Qdrant
|
||||||
@@ -20,11 +14,23 @@ class Settings:
|
|||||||
COLLECTION_PREFIX: str = os.getenv("MINDNET_PREFIX", "mindnet")
|
COLLECTION_PREFIX: str = os.getenv("MINDNET_PREFIX", "mindnet")
|
||||||
VECTOR_SIZE: int = int(os.getenv("MINDNET_VECTOR_SIZE", "384"))
|
VECTOR_SIZE: int = int(os.getenv("MINDNET_VECTOR_SIZE", "384"))
|
||||||
DISTANCE: str = os.getenv("MINDNET_DISTANCE", "Cosine")
|
DISTANCE: str = os.getenv("MINDNET_DISTANCE", "Cosine")
|
||||||
|
|
||||||
# Embeddings
|
# Embeddings
|
||||||
MODEL_NAME: str = os.getenv("MINDNET_MODEL", "sentence-transformers/all-MiniLM-L6-v2")
|
MODEL_NAME: str = os.getenv("MINDNET_MODEL", "sentence-transformers/all-MiniLM-L6-v2")
|
||||||
|
|
||||||
|
# WP-05 LLM / Ollama
|
||||||
|
OLLAMA_URL: str = os.getenv("MINDNET_OLLAMA_URL", "http://127.0.0.1:11434")
|
||||||
|
LLM_MODEL: str = os.getenv("MINDNET_LLM_MODEL", "phi3:mini")
|
||||||
|
PROMPTS_PATH: str = os.getenv("MINDNET_PROMPTS_PATH", "config/prompts.yaml")
|
||||||
|
|
||||||
|
# NEU für WP-06
|
||||||
|
LLM_TIMEOUT: float = float(os.getenv("MINDNET_LLM_TIMEOUT", "120.0"))
|
||||||
|
DECISION_CONFIG_PATH: str = os.getenv("MINDNET_DECISION_CONFIG", "config/decision_engine.yaml")
|
||||||
|
|
||||||
# API
|
# API
|
||||||
DEBUG: bool = os.getenv("DEBUG", "false").lower() == "true"
|
DEBUG: bool = os.getenv("DEBUG", "false").lower() == "true"
|
||||||
# WP-04 Retriever Defaults (optional; können per ENV überschrieben werden)
|
|
||||||
|
# WP-04 Retriever Defaults
|
||||||
RETRIEVER_W_SEM: float = float(os.getenv("MINDNET_WP04_W_SEM", "0.70"))
|
RETRIEVER_W_SEM: float = float(os.getenv("MINDNET_WP04_W_SEM", "0.70"))
|
||||||
RETRIEVER_W_EDGE: float = float(os.getenv("MINDNET_WP04_W_EDGE", "0.25"))
|
RETRIEVER_W_EDGE: float = float(os.getenv("MINDNET_WP04_W_EDGE", "0.25"))
|
||||||
RETRIEVER_W_CENT: float = float(os.getenv("MINDNET_WP04_W_CENT", "0.05"))
|
RETRIEVER_W_CENT: float = float(os.getenv("MINDNET_WP04_W_CENT", "0.05"))
|
||||||
|
|||||||
+67
-116
@@ -1,28 +1,22 @@
|
|||||||
#!/usr/bin/env python3
|
#!/usr/bin/env python3
|
||||||
# -*- coding: utf-8 -*-
|
# -*- coding: utf-8 -*-
|
||||||
"""
|
"""
|
||||||
app/core/graph_adapter.py — Adjazenzaufbau & Subgraph-Expansion (WP-04)
|
app/core/graph_adapter.py — Adjazenzaufbau & Subgraph-Expansion
|
||||||
|
|
||||||
Zweck:
|
Zweck:
|
||||||
Baut aus Qdrant-Edges (Collection: *_edges) einen leichten In-Memory-Graph
|
Baut aus Qdrant-Edges (Collection: *_edges) einen leichten In-Memory-Graph.
|
||||||
und liefert Edge-basierte Kennzahlen (In-Degree, Out-Degree, edge_bonus).
|
|
||||||
|
|
||||||
Kompatibilität:
|
Kompatibilität:
|
||||||
- Python 3.12+, qdrant-client 1.x
|
- WP-04a: Liefert Scores (edge_bonus, centrality).
|
||||||
- Wird von app/core/retriever.py im Hybrid-Modus genutzt.
|
- WP-04b: Liefert jetzt auch Struktur-Daten für Erklärungen (Reverse-Lookup).
|
||||||
- Signaturen bleiben kompatibel zu den bestehenden Tests
|
|
||||||
(tests/test_retriever_edges.py patcht expand()).
|
|
||||||
|
|
||||||
Version:
|
Version:
|
||||||
0.3.1 (2025-12-04 – note_id-bewusste Expansion:
|
0.4.0 (Update für WP-04b: Reverse Adjacency für Explainability)
|
||||||
* Seeds = Note-IDs
|
|
||||||
* Subgraph pflegt zusätzlich Adjazenz auf note_id-Basis,
|
|
||||||
damit der Retriever mit note_id arbeiten kann)
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
from typing import Dict, List, Optional, DefaultDict
|
from typing import Dict, List, Optional, DefaultDict, Any
|
||||||
from collections import defaultdict
|
from collections import defaultdict
|
||||||
|
|
||||||
from qdrant_client import QdrantClient
|
from qdrant_client import QdrantClient
|
||||||
@@ -30,36 +24,27 @@ from qdrant_client.http import models as rest
|
|||||||
|
|
||||||
from app.core.qdrant import collection_names
|
from app.core.qdrant import collection_names
|
||||||
|
|
||||||
# Legacy-Import (wird aktuell nicht mehr verwendet, bleibt aber erhalten,
|
# Legacy-Import Fallback
|
||||||
# damit bestehende Importe/Mocks nicht brechen).
|
|
||||||
try: # pragma: no cover
|
try: # pragma: no cover
|
||||||
from app.core.qdrant_points import get_edges_for_sources # type: ignore
|
from app.core.qdrant_points import get_edges_for_sources # type: ignore
|
||||||
except Exception: # pragma: no cover
|
except Exception: # pragma: no cover
|
||||||
get_edges_for_sources = None # type: ignore
|
get_edges_for_sources = None # type: ignore
|
||||||
|
|
||||||
|
|
||||||
# Basisgewichte je Edge-Typ.
|
# Basisgewichte je Edge-Typ (WP-04a Config)
|
||||||
# Diese Werte werden mit der in der Edge-Payload hinterlegten "confidence"
|
|
||||||
# multipliziert, falls vorhanden.
|
|
||||||
#
|
|
||||||
# Hinweis:
|
|
||||||
# - Strukturkanten (belongs_to, next/prev) sind schwächer gewichtet.
|
|
||||||
# - Wissenskanten (depends_on, related_to, similar_to, references) erhalten
|
|
||||||
# höhere Basisgewichte, damit sie sich im Retriever bemerkbar machen.
|
|
||||||
EDGE_BASE_WEIGHTS: Dict[str, float] = {
|
EDGE_BASE_WEIGHTS: Dict[str, float] = {
|
||||||
# Struktur / Navigationskanten
|
# Struktur
|
||||||
"belongs_to": 0.10,
|
"belongs_to": 0.10,
|
||||||
"next": 0.06,
|
"next": 0.06,
|
||||||
"prev": 0.06,
|
"prev": 0.06,
|
||||||
"backlink": 0.04,
|
"backlink": 0.04,
|
||||||
"references_at": 0.08,
|
"references_at": 0.08,
|
||||||
|
|
||||||
# Wissenskanten
|
# Wissen
|
||||||
"references": 0.20,
|
"references": 0.20,
|
||||||
"depends_on": 0.18,
|
"depends_on": 0.18,
|
||||||
"related_to": 0.15,
|
"related_to": 0.15,
|
||||||
"similar_to": 0.12,
|
"similar_to": 0.12,
|
||||||
# weitere Typen erhalten per Default 0.0 und wirken nur über centrality
|
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
@@ -77,11 +62,8 @@ def _edge_weight(pl: Dict) -> float:
|
|||||||
if conf is None:
|
if conf is None:
|
||||||
return base
|
return base
|
||||||
|
|
||||||
# Confidence vorsichtig in [0.0, 1.0] clampen
|
if conf < 0.0: conf = 0.0
|
||||||
if conf < 0.0:
|
if conf > 1.0: conf = 1.0
|
||||||
conf = 0.0
|
|
||||||
if conf > 1.0:
|
|
||||||
conf = 1.0
|
|
||||||
|
|
||||||
return base * conf
|
return base * conf
|
||||||
|
|
||||||
@@ -95,48 +77,34 @@ def _fetch_edges(
|
|||||||
) -> List[Dict]:
|
) -> List[Dict]:
|
||||||
"""
|
"""
|
||||||
Holt Edges direkt aus der *_edges Collection.
|
Holt Edges direkt aus der *_edges Collection.
|
||||||
|
Filter: source_id IN seeds OR target_id IN seeds OR note_id IN seeds
|
||||||
Filter:
|
|
||||||
- source_id IN seeds ODER target_id IN seeds ODER note_id IN seeds
|
|
||||||
- optional: kind IN edge_types
|
|
||||||
"""
|
"""
|
||||||
if not seeds or limit <= 0:
|
if not seeds or limit <= 0:
|
||||||
return []
|
return []
|
||||||
|
|
||||||
_, _, edges_col = collection_names(prefix)
|
_, _, edges_col = collection_names(prefix)
|
||||||
|
|
||||||
# OR über source_id / target_id / note_id für alle Seeds
|
|
||||||
seed_conditions = []
|
seed_conditions = []
|
||||||
for field in ("source_id", "target_id", "note_id"):
|
for field in ("source_id", "target_id", "note_id"):
|
||||||
for s in seeds:
|
for s in seeds:
|
||||||
seed_conditions.append(
|
seed_conditions.append(
|
||||||
rest.FieldCondition(
|
rest.FieldCondition(key=field, match=rest.MatchValue(value=str(s)))
|
||||||
key=field,
|
|
||||||
match=rest.MatchValue(value=str(s)),
|
|
||||||
)
|
|
||||||
)
|
)
|
||||||
seeds_filter = rest.Filter(should=seed_conditions) if seed_conditions else None
|
seeds_filter = rest.Filter(should=seed_conditions) if seed_conditions else None
|
||||||
|
|
||||||
# Optional: Filter auf bestimmte Edge-Typen (kind)
|
|
||||||
type_filter = None
|
type_filter = None
|
||||||
if edge_types:
|
if edge_types:
|
||||||
type_conds = [
|
type_conds = [
|
||||||
rest.FieldCondition(
|
rest.FieldCondition(key="kind", match=rest.MatchValue(value=str(k)))
|
||||||
key="kind",
|
|
||||||
match=rest.MatchValue(value=str(k)),
|
|
||||||
)
|
|
||||||
for k in edge_types
|
for k in edge_types
|
||||||
]
|
]
|
||||||
type_filter = rest.Filter(should=type_conds)
|
type_filter = rest.Filter(should=type_conds)
|
||||||
|
|
||||||
flt = None
|
|
||||||
must = []
|
must = []
|
||||||
if seeds_filter:
|
if seeds_filter: must.append(seeds_filter)
|
||||||
must.append(seeds_filter)
|
if type_filter: must.append(type_filter)
|
||||||
if type_filter:
|
|
||||||
must.append(type_filter)
|
flt = rest.Filter(must=must) if must else None
|
||||||
if must:
|
|
||||||
flt = rest.Filter(must=must)
|
|
||||||
|
|
||||||
pts, _ = client.scroll(
|
pts, _ = client.scroll(
|
||||||
collection_name=edges_col,
|
collection_name=edges_col,
|
||||||
@@ -155,28 +123,21 @@ def _fetch_edges(
|
|||||||
|
|
||||||
|
|
||||||
class Subgraph:
|
class Subgraph:
|
||||||
"""Leichtgewichtiger Subgraph mit Adjazenzlisten & einfachen Kennzahlen."""
|
"""Leichtgewichtiger Subgraph mit Adjazenzlisten & Kennzahlen."""
|
||||||
|
|
||||||
def __init__(self) -> None:
|
def __init__(self) -> None:
|
||||||
|
# Forward: source -> [targets]
|
||||||
self.adj: DefaultDict[str, List[Dict]] = defaultdict(list)
|
self.adj: DefaultDict[str, List[Dict]] = defaultdict(list)
|
||||||
|
# Reverse: target -> [sources] (Neu für WP-04b Explanation)
|
||||||
|
self.reverse_adj: DefaultDict[str, List[Dict]] = defaultdict(list)
|
||||||
|
|
||||||
self.in_degree: DefaultDict[str, int] = defaultdict(int)
|
self.in_degree: DefaultDict[str, int] = defaultdict(int)
|
||||||
self.out_degree: DefaultDict[str, int] = defaultdict(int)
|
self.out_degree: DefaultDict[str, int] = defaultdict(int)
|
||||||
|
|
||||||
def add_edge(self, e: Dict) -> None:
|
def add_edge(self, e: Dict) -> None:
|
||||||
"""
|
"""
|
||||||
Fügt eine Kante zum Subgraph hinzu.
|
Fügt eine Kante hinzu und aktualisiert Forward/Reverse Indizes.
|
||||||
|
e muss enthalten: source, target, kind, weight.
|
||||||
e enthält:
|
|
||||||
- source: Knoten-ID (z. B. source_id)
|
|
||||||
- target: Knoten-ID (z. B. target_id)
|
|
||||||
- kind: Kantentyp
|
|
||||||
- weight: bereits berechnetes Gewicht
|
|
||||||
- note_id: (optional) Kontext-Note dieser Kante
|
|
||||||
|
|
||||||
Wichtig für den Retriever:
|
|
||||||
- Wir pflegen Adjazenz primär unter `source`.
|
|
||||||
- Zusätzlich pflegen wir, falls vorhanden, eine Adjazenz
|
|
||||||
unter `note_id`, damit der Retriever mit note_id arbeiten kann.
|
|
||||||
"""
|
"""
|
||||||
src = e.get("source")
|
src = e.get("source")
|
||||||
tgt = e.get("target")
|
tgt = e.get("target")
|
||||||
@@ -187,65 +148,57 @@ class Subgraph:
|
|||||||
if not src or not tgt:
|
if not src or not tgt:
|
||||||
return
|
return
|
||||||
|
|
||||||
# Primäre Adjazenz (z. B. source_id → target_id)
|
# 1. Primäre Adjazenz (Forward)
|
||||||
self.adj[src].append(
|
edge_data = {"target": tgt, "kind": kind, "weight": weight}
|
||||||
{
|
self.adj[src].append(edge_data)
|
||||||
"target": tgt,
|
|
||||||
"kind": kind,
|
|
||||||
"weight": weight,
|
|
||||||
}
|
|
||||||
)
|
|
||||||
self.out_degree[src] += 1
|
self.out_degree[src] += 1
|
||||||
self.in_degree[tgt] += 1
|
self.in_degree[tgt] += 1
|
||||||
|
|
||||||
# Sekundäre Adjazenz auf Note-Ebene:
|
# 2. Reverse Adjazenz (Neu für Explanation)
|
||||||
# Falls eine Kontext-Note existiert, bekommt diese ebenfalls
|
# Wir speichern, woher die Kante kam.
|
||||||
# "Ausgangskanten" angerechnet. So kann der Retriever über note_id
|
rev_data = {"source": src, "kind": kind, "weight": weight}
|
||||||
# edge_bonus(...) und centrality_bonus(...) abfragen.
|
self.reverse_adj[tgt].append(rev_data)
|
||||||
if owner:
|
|
||||||
# same edge unter owner registrieren (falls nicht identisch mit src),
|
|
||||||
# damit edge_bonus(owner) > 0 werden kann.
|
|
||||||
if owner != src:
|
|
||||||
self.adj[owner].append(
|
|
||||||
{
|
|
||||||
"target": tgt,
|
|
||||||
"kind": kind,
|
|
||||||
"weight": weight,
|
|
||||||
}
|
|
||||||
)
|
|
||||||
self.out_degree[owner] += 1
|
|
||||||
|
|
||||||
# Zentralität der Kontext-Note leicht erhöhen
|
# 3. Kontext-Note Handling (Forward & Reverse)
|
||||||
|
# Wenn eine Kante "im Kontext einer Note" (owner) definiert ist,
|
||||||
|
# schreiben wir sie der Note gut, damit der Retriever Scores auf Note-Ebene findet.
|
||||||
|
if owner and owner != src:
|
||||||
|
# Forward: Owner -> Target
|
||||||
|
self.adj[owner].append(edge_data)
|
||||||
|
self.out_degree[owner] += 1
|
||||||
|
|
||||||
|
# Reverse: Target wird vom Owner referenziert (indirekt)
|
||||||
if owner != tgt:
|
if owner != tgt:
|
||||||
self.in_degree[owner] += 1
|
rev_owner_data = {"source": owner, "kind": kind, "weight": weight, "via_context": True}
|
||||||
|
self.reverse_adj[tgt].append(rev_owner_data)
|
||||||
|
self.in_degree[owner] += 1 # Leichter Centrality Boost für den Owner
|
||||||
|
|
||||||
def aggregate_edge_bonus(self, node_id: str) -> float:
|
def aggregate_edge_bonus(self, node_id: str) -> float:
|
||||||
"""
|
"""Summe der ausgehenden Kantengewichte (Hub-Score)."""
|
||||||
Summe der ausgehenden Kantengewichte für einen Knoten.
|
|
||||||
"""
|
|
||||||
return sum(edge["weight"] for edge in self.adj.get(node_id, []))
|
return sum(edge["weight"] for edge in self.adj.get(node_id, []))
|
||||||
|
|
||||||
def edge_bonus(self, node_id: str) -> float:
|
def edge_bonus(self, node_id: str) -> float:
|
||||||
"""
|
"""API für Retriever (WP-04a Kompatibilität)."""
|
||||||
Kompatibilitäts-Methode für den Retriever.
|
|
||||||
|
|
||||||
Der Retriever ruft subgraph.edge_bonus(node_id) auf. Intern verwenden
|
|
||||||
wir aggregate_edge_bonus(...), um bestehende Tests nicht zu brechen.
|
|
||||||
"""
|
|
||||||
return self.aggregate_edge_bonus(node_id)
|
return self.aggregate_edge_bonus(node_id)
|
||||||
|
|
||||||
def centrality_bonus(self, node_id: str) -> float:
|
def centrality_bonus(self, node_id: str) -> float:
|
||||||
"""
|
"""Log-gedämpfte Zentralität (In-Degree)."""
|
||||||
Einfache log-gedämpfte Zentralität auf Basis des In-Degree.
|
|
||||||
Obergrenze: 0.15
|
|
||||||
"""
|
|
||||||
import math
|
import math
|
||||||
|
|
||||||
indeg = self.in_degree.get(node_id, 0)
|
indeg = self.in_degree.get(node_id, 0)
|
||||||
if indeg <= 0:
|
if indeg <= 0:
|
||||||
return 0.0
|
return 0.0
|
||||||
return min(math.log1p(indeg) / 10.0, 0.15)
|
return min(math.log1p(indeg) / 10.0, 0.15)
|
||||||
|
|
||||||
|
# --- WP-04b Explanation Helpers ---
|
||||||
|
|
||||||
|
def get_outgoing_edges(self, node_id: str) -> List[Dict[str, Any]]:
|
||||||
|
"""Liefert Liste aller Ziele, auf die dieser Knoten zeigt."""
|
||||||
|
return self.adj.get(node_id, [])
|
||||||
|
|
||||||
|
def get_incoming_edges(self, node_id: str) -> List[Dict[str, Any]]:
|
||||||
|
"""Liefert Liste aller Quellen, die auf diesen Knoten zeigen."""
|
||||||
|
return self.reverse_adj.get(node_id, [])
|
||||||
|
|
||||||
|
|
||||||
def expand(
|
def expand(
|
||||||
client: QdrantClient,
|
client: QdrantClient,
|
||||||
@@ -255,12 +208,7 @@ def expand(
|
|||||||
edge_types: Optional[List[str]] = None,
|
edge_types: Optional[List[str]] = None,
|
||||||
) -> Subgraph:
|
) -> Subgraph:
|
||||||
"""
|
"""
|
||||||
Expandiert ab Seeds entlang von Edges (bis `depth`), optional gefiltert
|
Expandiert ab Seeds entlang von Edges (bis `depth`).
|
||||||
nach Edge-Typen.
|
|
||||||
|
|
||||||
Seeds sind stabile payload-IDs (in unserem Fall vor allem note_id).
|
|
||||||
Es werden Edges berücksichtigt, bei denen source_id ODER target_id ODER
|
|
||||||
note_id einem der Seeds entspricht.
|
|
||||||
"""
|
"""
|
||||||
sg = Subgraph()
|
sg = Subgraph()
|
||||||
frontier = set(seeds)
|
frontier = set(seeds)
|
||||||
@@ -284,19 +232,22 @@ def expand(
|
|||||||
for pl in edges_payloads:
|
for pl in edges_payloads:
|
||||||
src = pl.get("source_id")
|
src = pl.get("source_id")
|
||||||
tgt = pl.get("target_id")
|
tgt = pl.get("target_id")
|
||||||
kind = pl.get("kind", "edge")
|
|
||||||
owner = pl.get("note_id")
|
# Skip invalid edges
|
||||||
|
if not src or not tgt:
|
||||||
|
continue
|
||||||
|
|
||||||
e = {
|
e = {
|
||||||
"source": src,
|
"source": src,
|
||||||
"target": tgt,
|
"target": tgt,
|
||||||
"kind": kind,
|
"kind": pl.get("kind", "edge"),
|
||||||
"weight": _edge_weight(pl),
|
"weight": _edge_weight(pl),
|
||||||
"note_id": owner,
|
"note_id": pl.get("note_id"),
|
||||||
}
|
}
|
||||||
sg.add_edge(e)
|
sg.add_edge(e)
|
||||||
|
|
||||||
if tgt:
|
# Nur weitersuchen, wenn Target noch nicht besucht
|
||||||
|
if tgt and tgt not in visited:
|
||||||
next_frontier.add(tgt)
|
next_frontier.add(tgt)
|
||||||
|
|
||||||
visited |= frontier
|
visited |= frontier
|
||||||
|
|||||||
+157
-121
@@ -1,12 +1,26 @@
|
|||||||
|
"""
|
||||||
|
app/core/retriever.py — Hybrider Such-Algorithmus
|
||||||
|
|
||||||
|
Version:
|
||||||
|
0.5.3 (WP-06 Fix: Populate 'payload' in QueryHit for meta-data access)
|
||||||
|
"""
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import os
|
import os
|
||||||
import time
|
import time
|
||||||
from functools import lru_cache
|
from functools import lru_cache
|
||||||
from typing import Any, Dict, List, Tuple, Iterable
|
from typing import Any, Dict, List, Tuple, Iterable, Optional
|
||||||
|
|
||||||
from app.config import get_settings
|
from app.config import get_settings
|
||||||
from app.models.dto import QueryRequest, QueryResponse, QueryHit
|
from app.models.dto import (
|
||||||
|
QueryRequest,
|
||||||
|
QueryResponse,
|
||||||
|
QueryHit,
|
||||||
|
Explanation,
|
||||||
|
ScoreBreakdown,
|
||||||
|
Reason,
|
||||||
|
EdgeDTO
|
||||||
|
)
|
||||||
import app.core.qdrant as qdr
|
import app.core.qdrant as qdr
|
||||||
import app.core.qdrant_points as qp
|
import app.core.qdrant_points as qp
|
||||||
import app.services.embeddings_client as ec
|
import app.services.embeddings_client as ec
|
||||||
@@ -14,29 +28,18 @@ import app.core.graph_adapter as ga
|
|||||||
|
|
||||||
try:
|
try:
|
||||||
import yaml # type: ignore[import]
|
import yaml # type: ignore[import]
|
||||||
except Exception: # pragma: no cover - Fallback, falls PyYAML nicht installiert ist
|
except Exception: # pragma: no cover
|
||||||
yaml = None # type: ignore[assignment]
|
yaml = None # type: ignore[assignment]
|
||||||
|
|
||||||
|
|
||||||
@lru_cache
|
@lru_cache
|
||||||
def _get_scoring_weights() -> Tuple[float, float, float]:
|
def _get_scoring_weights() -> Tuple[float, float, float]:
|
||||||
"""Liefert (semantic_weight, edge_weight, centrality_weight) für den Retriever.
|
"""Liefert (semantic_weight, edge_weight, centrality_weight) für den Retriever."""
|
||||||
|
|
||||||
Priorität:
|
|
||||||
1. Werte aus config/retriever.yaml (falls vorhanden und gültig),
|
|
||||||
Abschnitt:
|
|
||||||
scoring:
|
|
||||||
semantic_weight: 1.0
|
|
||||||
edge_weight: 0.5
|
|
||||||
centrality_weight: 0.5
|
|
||||||
2. Fallback auf Settings.RETRIEVER_W_* (ENV-basiert).
|
|
||||||
"""
|
|
||||||
settings = get_settings()
|
settings = get_settings()
|
||||||
sem = float(getattr(settings, "RETRIEVER_W_SEM", 1.0))
|
sem = float(getattr(settings, "RETRIEVER_W_SEM", 1.0))
|
||||||
edge = float(getattr(settings, "RETRIEVER_W_EDGE", 0.0))
|
edge = float(getattr(settings, "RETRIEVER_W_EDGE", 0.0))
|
||||||
cent = float(getattr(settings, "RETRIEVER_W_CENT", 0.0))
|
cent = float(getattr(settings, "RETRIEVER_W_CENT", 0.0))
|
||||||
|
|
||||||
# YAML-Override, falls konfiguriert
|
|
||||||
config_path = os.getenv("MINDNET_RETRIEVER_CONFIG", "config/retriever.yaml")
|
config_path = os.getenv("MINDNET_RETRIEVER_CONFIG", "config/retriever.yaml")
|
||||||
if yaml is None:
|
if yaml is None:
|
||||||
return sem, edge, cent
|
return sem, edge, cent
|
||||||
@@ -49,26 +52,19 @@ def _get_scoring_weights() -> Tuple[float, float, float]:
|
|||||||
edge = float(scoring.get("edge_weight", edge))
|
edge = float(scoring.get("edge_weight", edge))
|
||||||
cent = float(scoring.get("centrality_weight", cent))
|
cent = float(scoring.get("centrality_weight", cent))
|
||||||
except Exception:
|
except Exception:
|
||||||
# Bei Fehlern in der YAML-Konfiguration defensiv auf Defaults zurückfallen
|
|
||||||
return sem, edge, cent
|
return sem, edge, cent
|
||||||
return sem, edge, cent
|
return sem, edge, cent
|
||||||
|
|
||||||
|
|
||||||
def _get_client_and_prefix() -> Tuple[Any, str]:
|
def _get_client_and_prefix() -> Tuple[Any, str]:
|
||||||
"""Liefert (QdrantClient, prefix) basierend auf QdrantConfig.from_env()."""
|
"""Liefert (QdrantClient, prefix)."""
|
||||||
cfg = qdr.QdrantConfig.from_env()
|
cfg = qdr.QdrantConfig.from_env()
|
||||||
client = qdr.get_client(cfg)
|
client = qdr.get_client(cfg)
|
||||||
return client, cfg.prefix
|
return client, cfg.prefix
|
||||||
|
|
||||||
|
|
||||||
def _get_query_vector(req: QueryRequest) -> List[float]:
|
def _get_query_vector(req: QueryRequest) -> List[float]:
|
||||||
"""
|
"""Liefert den Query-Vektor aus dem Request."""
|
||||||
Liefert den Query-Vektor aus dem Request.
|
|
||||||
|
|
||||||
- Falls req.query_vector gesetzt ist, wird dieser unverändert genutzt.
|
|
||||||
- Andernfalls wird req.query über den Embedding-Service in einen Vektor
|
|
||||||
transformiert.
|
|
||||||
"""
|
|
||||||
if req.query_vector:
|
if req.query_vector:
|
||||||
return list(req.query_vector)
|
return list(req.query_vector)
|
||||||
|
|
||||||
@@ -78,12 +74,10 @@ def _get_query_vector(req: QueryRequest) -> List[float]:
|
|||||||
settings = get_settings()
|
settings = get_settings()
|
||||||
model_name = settings.MODEL_NAME
|
model_name = settings.MODEL_NAME
|
||||||
|
|
||||||
# Kompatibel mit Fakes in Unit-Tests (ohne model_name-Parameter)
|
|
||||||
try:
|
try:
|
||||||
return ec.embed_text(req.query, model_name=model_name) # type: ignore[call-arg]
|
return ec.embed_text(req.query, model_name=model_name)
|
||||||
except TypeError:
|
except TypeError:
|
||||||
# Fallback: einfache Signatur embed_text(text)
|
return ec.embed_text(req.query)
|
||||||
return ec.embed_text(req.query) # type: ignore[call-arg]
|
|
||||||
|
|
||||||
|
|
||||||
def _semantic_hits(
|
def _semantic_hits(
|
||||||
@@ -93,13 +87,7 @@ def _semantic_hits(
|
|||||||
top_k: int,
|
top_k: int,
|
||||||
filters: Dict[str, Any] | None = None,
|
filters: Dict[str, Any] | None = None,
|
||||||
) -> List[Tuple[str, float, Dict[str, Any]]]:
|
) -> List[Tuple[str, float, Dict[str, Any]]]:
|
||||||
"""Führt eine semantische Suche über mindnet_chunks aus und liefert Roh-Treffer.
|
"""Führt eine semantische Suche aus."""
|
||||||
|
|
||||||
Rückgabeformat: Liste von (point_id, score, payload)
|
|
||||||
|
|
||||||
Erwartetes Format von qp.search_chunks_by_vector:
|
|
||||||
List[Tuple[str, float, dict]]
|
|
||||||
"""
|
|
||||||
flt = filters or None
|
flt = filters or None
|
||||||
raw_hits = qp.search_chunks_by_vector(client, prefix, vector, top=top_k, filters=flt)
|
raw_hits = qp.search_chunks_by_vector(client, prefix, vector, top=top_k, filters=flt)
|
||||||
results: List[Tuple[str, float, Dict[str, Any]]] = []
|
results: List[Tuple[str, float, Dict[str, Any]]] = []
|
||||||
@@ -108,30 +96,13 @@ def _semantic_hits(
|
|||||||
return results
|
return results
|
||||||
|
|
||||||
|
|
||||||
def _get_semantic_score_and_payload(
|
|
||||||
hit: Tuple[str, float, Dict[str, Any]]
|
|
||||||
) -> Tuple[float, Dict[str, Any]]:
|
|
||||||
"""Extrahiert semantic_score und Payload aus einem Raw-Hit."""
|
|
||||||
_, score, payload = hit
|
|
||||||
return float(score), payload or {}
|
|
||||||
|
|
||||||
|
|
||||||
def _compute_total_score(
|
def _compute_total_score(
|
||||||
semantic_score: float,
|
semantic_score: float,
|
||||||
payload: Dict[str, Any],
|
payload: Dict[str, Any],
|
||||||
edge_bonus: float = 0.0,
|
edge_bonus: float = 0.0,
|
||||||
cent_bonus: float = 0.0,
|
cent_bonus: float = 0.0,
|
||||||
) -> Tuple[float, float, float]:
|
) -> Tuple[float, float, float]:
|
||||||
"""Berechnet total_score aus semantic_score, retriever_weight und Graph-Boni.
|
"""Berechnet total_score."""
|
||||||
|
|
||||||
Formel (WP-04, konfigurierbar über config/retriever.yaml bzw. ENV):
|
|
||||||
total_score = W_sem * semantic_score * max(retriever_weight, 0.0)
|
|
||||||
+ W_edge * edge_bonus
|
|
||||||
+ W_cent * cent_bonus
|
|
||||||
|
|
||||||
- retriever_weight stammt aus dem Chunk-Payload (types.yaml).
|
|
||||||
- W_sem / W_edge / W_cent kommen aus _get_scoring_weights().
|
|
||||||
"""
|
|
||||||
raw_weight = payload.get("retriever_weight", 1.0)
|
raw_weight = payload.get("retriever_weight", 1.0)
|
||||||
try:
|
try:
|
||||||
weight = float(raw_weight)
|
weight = float(raw_weight)
|
||||||
@@ -145,12 +116,84 @@ def _compute_total_score(
|
|||||||
return float(total), float(edge_bonus), float(cent_bonus)
|
return float(total), float(edge_bonus), float(cent_bonus)
|
||||||
|
|
||||||
|
|
||||||
def _extract_expand_options(req: QueryRequest) -> Tuple[int, List[str] | None]:
|
# --- WP-04b Explanation Logic ---
|
||||||
"""Extrahiert depth und edge_types aus req.expand, falls vorhanden.
|
|
||||||
|
|
||||||
- Falls expand nicht gesetzt ist: depth=0, edge_types=None (keine Expansion).
|
def _build_explanation(
|
||||||
- Unterstützt sowohl Pydantic-Modelle als auch plain dicts.
|
semantic_score: float,
|
||||||
"""
|
payload: Dict[str, Any],
|
||||||
|
edge_bonus: float,
|
||||||
|
cent_bonus: float,
|
||||||
|
subgraph: Optional[ga.Subgraph],
|
||||||
|
node_key: Optional[str]
|
||||||
|
) -> Explanation:
|
||||||
|
"""Erstellt ein Explanation-Objekt."""
|
||||||
|
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))
|
||||||
|
except (TypeError, ValueError):
|
||||||
|
type_weight = 1.0
|
||||||
|
|
||||||
|
note_type = payload.get("type", "unknown")
|
||||||
|
|
||||||
|
breakdown = ScoreBreakdown(
|
||||||
|
semantic_contribution=(sem_w * semantic_score * type_weight),
|
||||||
|
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,
|
||||||
|
node_weight=type_weight
|
||||||
|
)
|
||||||
|
|
||||||
|
reasons: List[Reason] = []
|
||||||
|
edges_dto: List[EdgeDTO] = []
|
||||||
|
|
||||||
|
if semantic_score > 0.85:
|
||||||
|
reasons.append(Reason(kind="semantic", message="Sehr hohe textuelle Übereinstimmung.", score_impact=breakdown.semantic_contribution))
|
||||||
|
elif semantic_score > 0.70:
|
||||||
|
reasons.append(Reason(kind="semantic", message="Gute textuelle Übereinstimmung.", score_impact=breakdown.semantic_contribution))
|
||||||
|
|
||||||
|
if type_weight != 1.0:
|
||||||
|
msg = "Bevorzugt" if type_weight > 1.0 else "Leicht abgewertet"
|
||||||
|
reasons.append(Reason(kind="type", message=f"{msg} aufgrund des Typs '{note_type}'.", score_impact=(sem_w * semantic_score * (type_weight - 1.0))))
|
||||||
|
|
||||||
|
if subgraph and node_key and edge_bonus > 0:
|
||||||
|
if hasattr(subgraph, "get_outgoing_edges"):
|
||||||
|
outgoing = subgraph.get_outgoing_edges(node_key)
|
||||||
|
for edge in outgoing:
|
||||||
|
target = edge.get("target", "Unknown")
|
||||||
|
kind = edge.get("kind", "edge")
|
||||||
|
weight = edge.get("weight", 0.0)
|
||||||
|
if weight > 0.05:
|
||||||
|
edges_dto.append(EdgeDTO(id=f"{node_key}->{target}:{kind}", kind=kind, source=node_key, target=target, weight=weight, direction="out"))
|
||||||
|
|
||||||
|
if hasattr(subgraph, "get_incoming_edges"):
|
||||||
|
incoming = subgraph.get_incoming_edges(node_key)
|
||||||
|
for edge in incoming:
|
||||||
|
src = edge.get("source", "Unknown")
|
||||||
|
kind = edge.get("kind", "edge")
|
||||||
|
weight = edge.get("weight", 0.0)
|
||||||
|
if weight > 0.05:
|
||||||
|
edges_dto.append(EdgeDTO(id=f"{src}->{node_key}:{kind}", kind=kind, source=src, target=node_key, weight=weight, direction="in"))
|
||||||
|
|
||||||
|
all_edges = sorted(edges_dto, key=lambda e: e.weight, reverse=True)
|
||||||
|
for top_edge in all_edges[:3]:
|
||||||
|
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}))
|
||||||
|
|
||||||
|
if cent_bonus > 0.01:
|
||||||
|
reasons.append(Reason(kind="centrality", message="Knoten liegt zentral im Kontext.", score_impact=breakdown.centrality_contribution))
|
||||||
|
|
||||||
|
return Explanation(breakdown=breakdown, reasons=reasons, related_edges=edges_dto if edges_dto else None)
|
||||||
|
|
||||||
|
|
||||||
|
def _extract_expand_options(req: QueryRequest) -> Tuple[int, List[str] | None]:
|
||||||
|
"""Extrahiert depth und edge_types."""
|
||||||
expand = getattr(req, "expand", None)
|
expand = getattr(req, "expand", None)
|
||||||
if not expand:
|
if not expand:
|
||||||
return 0, None
|
return 0, None
|
||||||
@@ -158,7 +201,6 @@ def _extract_expand_options(req: QueryRequest) -> Tuple[int, List[str] | None]:
|
|||||||
depth = 1
|
depth = 1
|
||||||
edge_types: List[str] | None = None
|
edge_types: List[str] | None = None
|
||||||
|
|
||||||
# Pydantic-Modell oder Objekt mit Attributen
|
|
||||||
if hasattr(expand, "depth") or hasattr(expand, "edge_types"):
|
if hasattr(expand, "depth") or hasattr(expand, "edge_types"):
|
||||||
depth = int(getattr(expand, "depth", 1) or 1)
|
depth = int(getattr(expand, "depth", 1) or 1)
|
||||||
types_val = getattr(expand, "edge_types", None)
|
types_val = getattr(expand, "edge_types", None)
|
||||||
@@ -166,7 +208,6 @@ def _extract_expand_options(req: QueryRequest) -> Tuple[int, List[str] | None]:
|
|||||||
edge_types = list(types_val)
|
edge_types = list(types_val)
|
||||||
return depth, edge_types
|
return depth, edge_types
|
||||||
|
|
||||||
# Plain dict
|
|
||||||
if isinstance(expand, dict):
|
if isinstance(expand, dict):
|
||||||
if "depth" in expand:
|
if "depth" in expand:
|
||||||
depth = int(expand.get("depth") or 1)
|
depth = int(expand.get("depth") or 1)
|
||||||
@@ -182,119 +223,114 @@ def _build_hits_from_semantic(
|
|||||||
top_k: int,
|
top_k: int,
|
||||||
used_mode: str,
|
used_mode: str,
|
||||||
subgraph: ga.Subgraph | None = None,
|
subgraph: ga.Subgraph | None = None,
|
||||||
|
explain: bool = False,
|
||||||
) -> QueryResponse:
|
) -> QueryResponse:
|
||||||
"""Baut aus Raw-Hits und optionalem Subgraph strukturierte QueryHits.
|
"""Baut strukturierte QueryHits."""
|
||||||
|
|
||||||
- Aggregation auf Note-Ebene (note_id),
|
|
||||||
- Berechnung von total_score unter Nutzung von retriever_weight + Graph-Boni,
|
|
||||||
- Rückgabe als QueryResponse mit Latenz.
|
|
||||||
"""
|
|
||||||
t0 = time.time()
|
t0 = time.time()
|
||||||
|
|
||||||
enriched: List[Tuple[str, float, Dict[str, Any], float, float, float]] = []
|
enriched: List[Tuple[str, float, Dict[str, Any], float, float, float]] = []
|
||||||
|
|
||||||
for pid, semantic_score, payload in hits:
|
for pid, semantic_score, payload in hits:
|
||||||
# Graph-Scores, falls Subgraph und stabiler Key vorhanden
|
|
||||||
edge_bonus = 0.0
|
edge_bonus = 0.0
|
||||||
cent_bonus = 0.0
|
cent_bonus = 0.0
|
||||||
if subgraph is not None:
|
node_key = payload.get("chunk_id") or payload.get("note_id")
|
||||||
node_key = payload.get("chunk_id") or payload.get("note_id")
|
|
||||||
if node_key:
|
|
||||||
try:
|
|
||||||
edge_bonus = float(subgraph.edge_bonus(node_key))
|
|
||||||
except Exception:
|
|
||||||
edge_bonus = 0.0
|
|
||||||
try:
|
|
||||||
cent_bonus = float(subgraph.centrality_bonus(node_key))
|
|
||||||
except Exception:
|
|
||||||
cent_bonus = 0.0
|
|
||||||
|
|
||||||
total, edge_bonus, cent_bonus = _compute_total_score(
|
if subgraph is not None and node_key:
|
||||||
semantic_score,
|
try:
|
||||||
payload,
|
edge_bonus = float(subgraph.edge_bonus(node_key))
|
||||||
edge_bonus=edge_bonus,
|
except Exception:
|
||||||
cent_bonus=cent_bonus,
|
edge_bonus = 0.0
|
||||||
)
|
try:
|
||||||
|
cent_bonus = float(subgraph.centrality_bonus(node_key))
|
||||||
|
except Exception:
|
||||||
|
cent_bonus = 0.0
|
||||||
|
|
||||||
|
total, edge_bonus, cent_bonus = _compute_total_score(semantic_score, payload, edge_bonus=edge_bonus, cent_bonus=cent_bonus)
|
||||||
enriched.append((pid, float(semantic_score), payload, total, edge_bonus, cent_bonus))
|
enriched.append((pid, float(semantic_score), payload, total, edge_bonus, cent_bonus))
|
||||||
|
|
||||||
# Sortierung nach total_score absteigend
|
|
||||||
enriched_sorted = sorted(enriched, key=lambda h: h[3], reverse=True)
|
enriched_sorted = sorted(enriched, key=lambda h: h[3], reverse=True)
|
||||||
limited = enriched_sorted[: max(1, top_k)]
|
limited = enriched_sorted[: max(1, top_k)]
|
||||||
|
|
||||||
results: List[QueryHit] = []
|
results: List[QueryHit] = []
|
||||||
for pid, semantic_score, payload, total, edge_bonus, cent_bonus in limited:
|
for pid, semantic_score, payload, total, edge_bonus, cent_bonus in limited:
|
||||||
note_id = payload.get("note_id")
|
explanation_obj = None
|
||||||
path = payload.get("path")
|
if explain:
|
||||||
# mindnet_chunks: section (aktuell genutzt); ältere Stände nutzen ggf. section_title
|
explanation_obj = _build_explanation(
|
||||||
section = payload.get("section") or payload.get("section_title")
|
|
||||||
|
|
||||||
results.append(
|
|
||||||
QueryHit(
|
|
||||||
node_id=str(pid),
|
|
||||||
note_id=note_id,
|
|
||||||
semantic_score=float(semantic_score),
|
semantic_score=float(semantic_score),
|
||||||
|
payload=payload,
|
||||||
edge_bonus=edge_bonus,
|
edge_bonus=edge_bonus,
|
||||||
centrality_bonus=cent_bonus,
|
cent_bonus=cent_bonus,
|
||||||
total_score=total,
|
subgraph=subgraph,
|
||||||
paths=None,
|
node_key=payload.get("chunk_id") or payload.get("note_id")
|
||||||
source={
|
|
||||||
"path": path,
|
|
||||||
"section": section,
|
|
||||||
},
|
|
||||||
)
|
)
|
||||||
)
|
|
||||||
|
text_content = payload.get("page_content") or payload.get("text") or payload.get("content")
|
||||||
|
|
||||||
|
results.append(QueryHit(
|
||||||
|
node_id=str(pid),
|
||||||
|
note_id=payload.get("note_id"),
|
||||||
|
semantic_score=float(semantic_score),
|
||||||
|
edge_bonus=edge_bonus,
|
||||||
|
centrality_bonus=cent_bonus,
|
||||||
|
total_score=total,
|
||||||
|
paths=None,
|
||||||
|
source={
|
||||||
|
"path": payload.get("path"),
|
||||||
|
"section": payload.get("section") or payload.get("section_title"),
|
||||||
|
"text": text_content
|
||||||
|
},
|
||||||
|
# --- FIX: Wir füllen das payload-Feld explizit ---
|
||||||
|
payload=payload,
|
||||||
|
explanation=explanation_obj
|
||||||
|
))
|
||||||
|
|
||||||
dt = int((time.time() - t0) * 1000)
|
dt = int((time.time() - t0) * 1000)
|
||||||
return QueryResponse(results=results, used_mode=used_mode, latency_ms=dt)
|
return QueryResponse(results=results, used_mode=used_mode, latency_ms=dt)
|
||||||
|
|
||||||
|
|
||||||
def semantic_retrieve(req: QueryRequest) -> QueryResponse:
|
def semantic_retrieve(req: QueryRequest) -> QueryResponse:
|
||||||
"""Reiner semantischer Retriever (ohne Edge-Expansion)."""
|
"""Reiner semantischer Retriever."""
|
||||||
client, prefix = _get_client_and_prefix()
|
client, prefix = _get_client_and_prefix()
|
||||||
vector = _get_query_vector(req)
|
vector = _get_query_vector(req)
|
||||||
top_k = req.top_k or get_settings().RETRIEVER_TOP_K
|
top_k = req.top_k or get_settings().RETRIEVER_TOP_K
|
||||||
|
|
||||||
hits = _semantic_hits(client, prefix, vector, top_k=top_k, filters=req.filters)
|
hits = _semantic_hits(client, prefix, vector, top_k=top_k, filters=req.filters)
|
||||||
return _build_hits_from_semantic(hits, top_k=top_k, used_mode="semantic", subgraph=None)
|
return _build_hits_from_semantic(hits, top_k=top_k, used_mode="semantic", subgraph=None, explain=req.explain)
|
||||||
|
|
||||||
|
|
||||||
def hybrid_retrieve(req: QueryRequest) -> QueryResponse:
|
def hybrid_retrieve(req: QueryRequest) -> QueryResponse:
|
||||||
"""Hybrid-Retriever: semantische Suche + optionale Edge-Expansion.
|
"""Hybrid-Retriever: semantische Suche + optionale Edge-Expansion."""
|
||||||
|
|
||||||
Aktueller Stand (Step 3):
|
|
||||||
- Semantische Suche über mindnet_chunks (wie semantic_retrieve),
|
|
||||||
- Bei expand.depth > 0 wird ein Subgraph aus mindnet_edges aufgebaut,
|
|
||||||
und edge_bonus / centrality_bonus in das Scoring einbezogen.
|
|
||||||
"""
|
|
||||||
client, prefix = _get_client_and_prefix()
|
client, prefix = _get_client_and_prefix()
|
||||||
|
|
||||||
# Query-Vektor:
|
|
||||||
# - Falls explizit gesetzt, unverändert nutzen.
|
|
||||||
# - Andernfalls über embed_text erzeugen.
|
|
||||||
if req.query_vector:
|
if req.query_vector:
|
||||||
vector = list(req.query_vector)
|
vector = list(req.query_vector)
|
||||||
else:
|
else:
|
||||||
vector = _get_query_vector(req)
|
vector = _get_query_vector(req)
|
||||||
|
|
||||||
top_k = req.top_k or get_settings().RETRIEVER_TOP_K
|
top_k = req.top_k or get_settings().RETRIEVER_TOP_K
|
||||||
|
|
||||||
hits = _semantic_hits(client, prefix, vector, top_k=top_k, filters=req.filters)
|
hits = _semantic_hits(client, prefix, vector, top_k=top_k, filters=req.filters)
|
||||||
|
|
||||||
depth, edge_types = _extract_expand_options(req)
|
depth, edge_types = _extract_expand_options(req)
|
||||||
subgraph: ga.Subgraph | None = None
|
subgraph: ga.Subgraph | None = None
|
||||||
if depth and depth > 0:
|
if depth and depth > 0:
|
||||||
# Seeds: stabile IDs aus dem Payload (chunk_id bevorzugt, sonst note_id)
|
|
||||||
seed_ids: List[str] = []
|
seed_ids: List[str] = []
|
||||||
for _pid, _score, payload in hits:
|
for _pid, _score, payload in hits:
|
||||||
key = payload.get("chunk_id") or payload.get("note_id")
|
key = payload.get("chunk_id") or payload.get("note_id")
|
||||||
if key and key not in seed_ids:
|
if key and key not in seed_ids:
|
||||||
seed_ids.append(key)
|
seed_ids.append(key)
|
||||||
|
|
||||||
if seed_ids:
|
if seed_ids:
|
||||||
try:
|
try:
|
||||||
subgraph = ga.expand(client, prefix, seed_ids, depth=depth, edge_types=edge_types)
|
subgraph = ga.expand(client, prefix, seed_ids, depth=depth, edge_types=edge_types)
|
||||||
except Exception:
|
except Exception:
|
||||||
# Edge-Expansion ist optional: bei Fehlern weiter ohne Graph-Boni
|
|
||||||
subgraph = None
|
subgraph = None
|
||||||
|
|
||||||
return _build_hits_from_semantic(hits, top_k=top_k, used_mode="hybrid", subgraph=subgraph)
|
return _build_hits_from_semantic(hits, top_k=top_k, used_mode="hybrid", subgraph=subgraph, explain=req.explain)
|
||||||
|
|
||||||
|
|
||||||
|
class Retriever:
|
||||||
|
"""
|
||||||
|
Wrapper-Klasse für WP-05 (Chat).
|
||||||
|
"""
|
||||||
|
def __init__(self):
|
||||||
|
pass
|
||||||
|
|
||||||
|
async def search(self, request: QueryRequest) -> QueryResponse:
|
||||||
|
return hybrid_retrieve(request)
|
||||||
+11
-8
@@ -1,40 +1,43 @@
|
|||||||
"""
|
"""
|
||||||
app/main.py — mindnet API bootstrap (WP-04 Hooks)
|
app/main.py — mindnet API bootstrap
|
||||||
Version: 0.4.2 • Stand: 2025-10-07
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
from fastapi import FastAPI
|
from fastapi import FastAPI
|
||||||
from .config import get_settings
|
from .config import get_settings
|
||||||
from .routers.embed_router import router as embed_router
|
from .routers.embed_router import router as embed_router
|
||||||
from .routers.qdrant_router import router as qdrant_router
|
from .routers.qdrant_router import router as qdrant_router
|
||||||
|
|
||||||
# WP-04 Router:
|
|
||||||
from .routers.query import router as query_router
|
from .routers.query import router as query_router
|
||||||
from .routers.graph import router as graph_router
|
from .routers.graph import router as graph_router
|
||||||
from .routers.tools import router as tools_router
|
from .routers.tools import router as tools_router
|
||||||
# Optional:
|
from .routers.feedback import router as feedback_router
|
||||||
|
# NEU: Chat Router (WP-05)
|
||||||
|
from .routers.chat import router as chat_router
|
||||||
|
|
||||||
try:
|
try:
|
||||||
from .routers.admin import router as admin_router
|
from .routers.admin import router as admin_router
|
||||||
except Exception:
|
except Exception:
|
||||||
admin_router = None
|
admin_router = None
|
||||||
|
|
||||||
def create_app() -> FastAPI:
|
def create_app() -> FastAPI:
|
||||||
app = FastAPI(title="mindnet API", version="0.1.0")
|
app = FastAPI(title="mindnet API", version="0.5.0") # Version bump WP-05
|
||||||
s = get_settings()
|
s = get_settings()
|
||||||
|
|
||||||
@app.get("/healthz")
|
@app.get("/healthz")
|
||||||
def healthz():
|
def healthz():
|
||||||
return {"status": "ok", "qdrant": s.QDRANT_URL, "prefix": s.COLLECTION_PREFIX}
|
return {"status": "ok", "qdrant": s.QDRANT_URL, "prefix": s.COLLECTION_PREFIX}
|
||||||
|
|
||||||
# Bestehende Router (unverändert)
|
|
||||||
app.include_router(embed_router)
|
app.include_router(embed_router)
|
||||||
app.include_router(qdrant_router)
|
app.include_router(qdrant_router)
|
||||||
|
|
||||||
# WP-04 Endpunkte
|
|
||||||
app.include_router(query_router, prefix="/query", tags=["query"])
|
app.include_router(query_router, prefix="/query", tags=["query"])
|
||||||
app.include_router(graph_router, prefix="/graph", tags=["graph"])
|
app.include_router(graph_router, prefix="/graph", tags=["graph"])
|
||||||
app.include_router(tools_router, prefix="/tools", tags=["tools"])
|
app.include_router(tools_router, prefix="/tools", tags=["tools"])
|
||||||
|
app.include_router(feedback_router, prefix="/feedback", tags=["feedback"])
|
||||||
|
|
||||||
|
# NEU: Chat Endpoint
|
||||||
|
app.include_router(chat_router, prefix="/chat", tags=["chat"])
|
||||||
|
|
||||||
if admin_router:
|
if admin_router:
|
||||||
app.include_router(admin_router, prefix="/admin", tags=["admin"])
|
app.include_router(admin_router, prefix="/admin", tags=["admin"])
|
||||||
|
|
||||||
|
|||||||
+86
-25
@@ -1,31 +1,26 @@
|
|||||||
"""
|
"""
|
||||||
app/models/dto.py — Pydantic-Modelle (DTOs) für WP-04 Endpunkte
|
app/models/dto.py — Pydantic-Modelle (DTOs) für WP-04/WP-05/WP-06
|
||||||
|
|
||||||
Zweck:
|
Zweck:
|
||||||
Laufzeit-Modelle für FastAPI (Requests/Responses), getrennt von JSON-Schemas.
|
Laufzeit-Modelle für FastAPI (Requests/Responses).
|
||||||
Deckt die Graph-/Retriever-Endpunkte ab, ohne bestehende Funktionen zu ändern.
|
WP-06 Update: Intent & Intent-Source in ChatResponse.
|
||||||
Kompatibilität:
|
|
||||||
Python 3.12+, Pydantic 2.x, FastAPI 0.110+
|
|
||||||
Version:
|
Version:
|
||||||
0.1.0 (Erstanlage für WP-04)
|
0.6.1 (WP-06: Decision Engine Transparency)
|
||||||
Stand:
|
Stand:
|
||||||
2025-10-07
|
2025-12-09
|
||||||
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
|
|
||||||
Änderungsverlauf:
|
|
||||||
0.1.0 (2025-10-07) – Erstanlage.
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
from pydantic import BaseModel
|
from pydantic import BaseModel, Field
|
||||||
from typing import List, Literal, Optional, Dict
|
from typing import List, Literal, Optional, Dict, Any
|
||||||
|
import uuid
|
||||||
|
|
||||||
EdgeKind = Literal["references", "references_at", "backlink", "next", "prev", "belongs_to"]
|
EdgeKind = Literal["references", "references_at", "backlink", "next", "prev", "belongs_to", "depends_on", "related_to", "similar_to"]
|
||||||
|
|
||||||
|
|
||||||
|
# --- Basis-DTOs ---
|
||||||
|
|
||||||
class NodeDTO(BaseModel):
|
class NodeDTO(BaseModel):
|
||||||
"""Darstellung eines Knotens (Note oder Chunk) im API-Graph."""
|
"""Darstellung eines Knotens (Note oder Chunk) im API-Graph."""
|
||||||
id: str
|
id: str
|
||||||
@@ -44,29 +39,80 @@ class NodeDTO(BaseModel):
|
|||||||
class EdgeDTO(BaseModel):
|
class EdgeDTO(BaseModel):
|
||||||
"""Darstellung einer Kante im API-Graph."""
|
"""Darstellung einer Kante im API-Graph."""
|
||||||
id: str
|
id: str
|
||||||
kind: EdgeKind
|
kind: str
|
||||||
source: str
|
source: str
|
||||||
target: str
|
target: str
|
||||||
weight: float
|
weight: float
|
||||||
direction: Literal["out", "in", "undirected"] = "out"
|
direction: Literal["out", "in", "undirected"] = "out"
|
||||||
|
|
||||||
|
|
||||||
|
# --- Request Models ---
|
||||||
|
|
||||||
class QueryRequest(BaseModel):
|
class QueryRequest(BaseModel):
|
||||||
"""
|
"""
|
||||||
Request für /query:
|
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
|
|
||||||
"""
|
"""
|
||||||
mode: Literal["semantic", "edge", "hybrid"] = "hybrid"
|
mode: Literal["semantic", "edge", "hybrid"] = "hybrid"
|
||||||
query: Optional[str] = None
|
query: Optional[str] = None
|
||||||
query_vector: Optional[List[float]] = None
|
query_vector: Optional[List[float]] = None
|
||||||
top_k: int = 10
|
top_k: int = 10
|
||||||
expand: Dict = {"depth": 1, "edge_types": ["references", "belongs_to", "prev", "next"]}
|
expand: Dict = {"depth": 1, "edge_types": ["references", "belongs_to", "prev", "next", "depends_on", "related_to"]}
|
||||||
filters: Optional[Dict] = None
|
filters: Optional[Dict] = None
|
||||||
ret: Dict = {"with_paths": True, "with_notes": True, "with_chunks": True}
|
ret: Dict = {"with_paths": True, "with_notes": True, "with_chunks": True}
|
||||||
|
explain: bool = False
|
||||||
|
|
||||||
|
|
||||||
|
class FeedbackRequest(BaseModel):
|
||||||
|
"""
|
||||||
|
User-Feedback zu einem spezifischen Treffer.
|
||||||
|
"""
|
||||||
|
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
|
||||||
|
|
||||||
|
|
||||||
|
class ChatRequest(BaseModel):
|
||||||
|
"""
|
||||||
|
WP-05: Request für /chat.
|
||||||
|
"""
|
||||||
|
message: str = Field(..., description="Die Nachricht des Users")
|
||||||
|
conversation_id: Optional[str] = Field(None, description="Optional: ID für Chat-Verlauf (noch nicht implementiert)")
|
||||||
|
# RAG Parameter (Override defaults)
|
||||||
|
top_k: int = 5
|
||||||
|
explain: bool = False
|
||||||
|
|
||||||
|
|
||||||
|
# --- WP-04b Explanation Models ---
|
||||||
|
|
||||||
|
class ScoreBreakdown(BaseModel):
|
||||||
|
"""Aufschlüsselung der Score-Komponenten."""
|
||||||
|
semantic_contribution: float
|
||||||
|
edge_contribution: float
|
||||||
|
centrality_contribution: float
|
||||||
|
raw_semantic: float
|
||||||
|
raw_edge_bonus: float
|
||||||
|
raw_centrality: float
|
||||||
|
node_weight: float
|
||||||
|
|
||||||
|
|
||||||
|
class Reason(BaseModel):
|
||||||
|
"""Ein semantischer Grund für das Ranking."""
|
||||||
|
kind: Literal["semantic", "edge", "type", "centrality"]
|
||||||
|
message: str
|
||||||
|
score_impact: Optional[float] = None
|
||||||
|
details: Optional[Dict[str, Any]] = None
|
||||||
|
|
||||||
|
|
||||||
|
class Explanation(BaseModel):
|
||||||
|
"""Container für alle Erklärungsdaten eines Treffers."""
|
||||||
|
breakdown: ScoreBreakdown
|
||||||
|
reasons: List[Reason]
|
||||||
|
related_edges: Optional[List[EdgeDTO]] = None
|
||||||
|
|
||||||
|
|
||||||
|
# --- Response Models ---
|
||||||
|
|
||||||
class QueryHit(BaseModel):
|
class QueryHit(BaseModel):
|
||||||
"""Einzelnes Trefferobjekt für /query."""
|
"""Einzelnes Trefferobjekt für /query."""
|
||||||
node_id: str
|
node_id: str
|
||||||
@@ -77,18 +123,33 @@ class QueryHit(BaseModel):
|
|||||||
total_score: float
|
total_score: float
|
||||||
paths: Optional[List[List[Dict]]] = None
|
paths: Optional[List[List[Dict]]] = None
|
||||||
source: Optional[Dict] = None
|
source: Optional[Dict] = None
|
||||||
|
payload: Optional[Dict] = None # Added for flexibility & WP-06 meta-data
|
||||||
|
explanation: Optional[Explanation] = None
|
||||||
|
|
||||||
|
|
||||||
class QueryResponse(BaseModel):
|
class QueryResponse(BaseModel):
|
||||||
"""Antwortstruktur für /query (Liste von Treffern + Telemetrie)."""
|
"""Antwortstruktur für /query."""
|
||||||
|
query_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
|
||||||
results: List[QueryHit]
|
results: List[QueryHit]
|
||||||
used_mode: str
|
used_mode: str
|
||||||
latency_ms: int
|
latency_ms: int
|
||||||
|
|
||||||
|
|
||||||
class GraphResponse(BaseModel):
|
class GraphResponse(BaseModel):
|
||||||
"""Antwortstruktur für /graph/{note_id} (Nachbarschaft)."""
|
"""Antwortstruktur für /graph/{note_id}."""
|
||||||
center_note_id: str
|
center_note_id: str
|
||||||
nodes: List[NodeDTO]
|
nodes: List[NodeDTO]
|
||||||
edges: List[EdgeDTO]
|
edges: List[EdgeDTO]
|
||||||
stats: Dict[str, int]
|
stats: Dict[str, int]
|
||||||
|
|
||||||
|
|
||||||
|
class ChatResponse(BaseModel):
|
||||||
|
"""
|
||||||
|
WP-05/06: Antwortstruktur für /chat.
|
||||||
|
"""
|
||||||
|
query_id: str = Field(..., description="Traceability ID (dieselbe wie für Search)")
|
||||||
|
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_source: Optional[str] = Field("Unknown", description="WP-06: Quelle der Intent-Erkennung (Keyword vs. LLM)")
|
||||||
@@ -0,0 +1,226 @@
|
|||||||
|
"""
|
||||||
|
app/routers/chat.py — RAG Endpunkt (WP-06 Hybrid Router v3)
|
||||||
|
Update: Transparenz über Intent-Source (Keyword vs. LLM).
|
||||||
|
"""
|
||||||
|
|
||||||
|
from fastapi import APIRouter, HTTPException, Depends
|
||||||
|
from typing import List, Dict, Any
|
||||||
|
import time
|
||||||
|
import uuid
|
||||||
|
import logging
|
||||||
|
import yaml
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
router = APIRouter()
|
||||||
|
logger = logging.getLogger(__name__)
|
||||||
|
|
||||||
|
# --- Helper: Config Loader ---
|
||||||
|
|
||||||
|
_DECISION_CONFIG_CACHE = None
|
||||||
|
|
||||||
|
def _load_decision_config() -> Dict[str, Any]:
|
||||||
|
settings = get_settings()
|
||||||
|
path = Path(settings.DECISION_CONFIG_PATH)
|
||||||
|
default_config = {
|
||||||
|
"strategies": {
|
||||||
|
"FACT": {"trigger_keywords": []}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if not path.exists():
|
||||||
|
logger.warning(f"Decision config not found at {path}, using defaults.")
|
||||||
|
return default_config
|
||||||
|
|
||||||
|
try:
|
||||||
|
with open(path, "r", encoding="utf-8") as f:
|
||||||
|
return yaml.safe_load(f)
|
||||||
|
except Exception as e:
|
||||||
|
logger.error(f"Failed to load decision config: {e}")
|
||||||
|
return default_config
|
||||||
|
|
||||||
|
def get_full_config() -> Dict[str, Any]:
|
||||||
|
global _DECISION_CONFIG_CACHE
|
||||||
|
if _DECISION_CONFIG_CACHE is None:
|
||||||
|
_DECISION_CONFIG_CACHE = _load_decision_config()
|
||||||
|
return _DECISION_CONFIG_CACHE
|
||||||
|
|
||||||
|
def get_decision_strategy(intent: str) -> Dict[str, Any]:
|
||||||
|
config = get_full_config()
|
||||||
|
strategies = config.get("strategies", {})
|
||||||
|
return strategies.get(intent, strategies.get("FACT", {}))
|
||||||
|
|
||||||
|
|
||||||
|
# --- Dependencies ---
|
||||||
|
|
||||||
|
def get_llm_service():
|
||||||
|
return LLMService()
|
||||||
|
|
||||||
|
def get_retriever():
|
||||||
|
return Retriever()
|
||||||
|
|
||||||
|
|
||||||
|
# --- Logic ---
|
||||||
|
|
||||||
|
def _build_enriched_context(hits: List[QueryHit]) -> str:
|
||||||
|
context_parts = []
|
||||||
|
for i, hit in enumerate(hits, 1):
|
||||||
|
source = hit.source or {}
|
||||||
|
content = (
|
||||||
|
source.get("text") or source.get("content") or
|
||||||
|
source.get("page_content") or source.get("chunk_text") or
|
||||||
|
"[Kein Text]"
|
||||||
|
)
|
||||||
|
title = hit.note_id or "Unbekannt"
|
||||||
|
|
||||||
|
# FIX: Wir holen den Typ aus Payload oder Source (Fallback)
|
||||||
|
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"
|
||||||
|
f"TYP: [{note_type}] (Score: {hit.total_score:.2f})\n"
|
||||||
|
f"INHALT:\n{content}\n"
|
||||||
|
)
|
||||||
|
context_parts.append(entry)
|
||||||
|
|
||||||
|
return "\n\n".join(context_parts)
|
||||||
|
|
||||||
|
async def _classify_intent(query: str, llm: LLMService) -> tuple[str, str]:
|
||||||
|
"""
|
||||||
|
Hybrid Router v3:
|
||||||
|
Gibt Tuple zurück: (Intent, Source)
|
||||||
|
"""
|
||||||
|
config = get_full_config()
|
||||||
|
strategies = config.get("strategies", {})
|
||||||
|
settings = config.get("settings", {})
|
||||||
|
|
||||||
|
query_lower = query.lower()
|
||||||
|
best_intent = None
|
||||||
|
max_match_length = 0
|
||||||
|
|
||||||
|
# 1. FAST PATH: Keywords
|
||||||
|
for intent_name, strategy in strategies.items():
|
||||||
|
if intent_name == "FACT": continue
|
||||||
|
keywords = strategy.get("trigger_keywords", [])
|
||||||
|
for k in keywords:
|
||||||
|
if k.lower() in query_lower:
|
||||||
|
if len(k) > max_match_length:
|
||||||
|
max_match_length = len(k)
|
||||||
|
best_intent = intent_name
|
||||||
|
|
||||||
|
if best_intent:
|
||||||
|
return best_intent, "Keyword (Fast Path)"
|
||||||
|
|
||||||
|
# 2. SLOW PATH: LLM Router
|
||||||
|
if settings.get("llm_fallback_enabled", False):
|
||||||
|
router_prompt_template = settings.get("llm_router_prompt", "")
|
||||||
|
if router_prompt_template:
|
||||||
|
prompt = router_prompt_template.replace("{query}", query)
|
||||||
|
logger.info("Keywords failed. Asking LLM for Intent...")
|
||||||
|
|
||||||
|
raw_response = await llm.generate_raw_response(prompt)
|
||||||
|
|
||||||
|
# Parsing logic
|
||||||
|
llm_output_upper = raw_response.upper()
|
||||||
|
found_intents = []
|
||||||
|
for strat_key in strategies.keys():
|
||||||
|
if strat_key in llm_output_upper:
|
||||||
|
found_intents.append(strat_key)
|
||||||
|
|
||||||
|
if len(found_intents) == 1:
|
||||||
|
return found_intents[0], "LLM Router (Slow Path)"
|
||||||
|
elif len(found_intents) > 1:
|
||||||
|
return found_intents[0], f"LLM Ambiguous {found_intents}"
|
||||||
|
else:
|
||||||
|
return "FACT", "LLM Fallback (No Match)"
|
||||||
|
|
||||||
|
return "FACT", "Default (No Match)"
|
||||||
|
|
||||||
|
@router.post("/", response_model=ChatResponse)
|
||||||
|
async def chat_endpoint(
|
||||||
|
request: ChatRequest,
|
||||||
|
llm: LLMService = Depends(get_llm_service),
|
||||||
|
retriever: Retriever = Depends(get_retriever)
|
||||||
|
):
|
||||||
|
start_time = time.time()
|
||||||
|
query_id = str(uuid.uuid4())
|
||||||
|
logger.info(f"Chat request [{query_id}]: {request.message[:50]}...")
|
||||||
|
|
||||||
|
try:
|
||||||
|
# 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)
|
||||||
|
inject_types = strategy.get("inject_types", [])
|
||||||
|
prompt_key = strategy.get("prompt_template", "rag_template")
|
||||||
|
prepend_instr = strategy.get("prepend_instruction", "")
|
||||||
|
|
||||||
|
# 2. Primary Retrieval
|
||||||
|
query_req = QueryRequest(
|
||||||
|
query=request.message,
|
||||||
|
mode="hybrid",
|
||||||
|
top_k=request.top_k,
|
||||||
|
explain=request.explain
|
||||||
|
)
|
||||||
|
retrieve_result = await retriever.search(query_req)
|
||||||
|
hits = retrieve_result.results
|
||||||
|
|
||||||
|
# 3. Strategic Retrieval
|
||||||
|
if inject_types:
|
||||||
|
logger.info(f"[{query_id}] Executing Strategic Retrieval for types: {inject_types}...")
|
||||||
|
strategy_req = QueryRequest(
|
||||||
|
query=request.message,
|
||||||
|
mode="hybrid",
|
||||||
|
top_k=3,
|
||||||
|
filters={"type": inject_types},
|
||||||
|
explain=False
|
||||||
|
)
|
||||||
|
strategy_result = await retriever.search(strategy_req)
|
||||||
|
|
||||||
|
existing_ids = {h.node_id for h in hits}
|
||||||
|
for strat_hit in strategy_result.results:
|
||||||
|
if strat_hit.node_id not in existing_ids:
|
||||||
|
hits.append(strat_hit)
|
||||||
|
|
||||||
|
# 4. Context Building
|
||||||
|
if not hits:
|
||||||
|
context_str = "Keine relevanten Notizen gefunden."
|
||||||
|
else:
|
||||||
|
context_str = _build_enriched_context(hits)
|
||||||
|
|
||||||
|
# 5. Generation
|
||||||
|
template = llm.prompts.get(prompt_key, "{context_str}\n\n{query}")
|
||||||
|
system_prompt = llm.prompts.get("system_prompt", "")
|
||||||
|
|
||||||
|
if prepend_instr:
|
||||||
|
context_str = f"{prepend_instr}\n\n{context_str}"
|
||||||
|
|
||||||
|
final_prompt = template.replace("{context_str}", context_str).replace("{query}", request.message)
|
||||||
|
|
||||||
|
logger.info(f"[{query_id}] Sending to LLM (Intent: {intent}, Template: {prompt_key})...")
|
||||||
|
|
||||||
|
# System-Prompt separat übergeben
|
||||||
|
answer_text = await llm.generate_raw_response(prompt=final_prompt, system=system_prompt)
|
||||||
|
|
||||||
|
duration_ms = int((time.time() - start_time) * 1000)
|
||||||
|
|
||||||
|
return ChatResponse(
|
||||||
|
query_id=query_id,
|
||||||
|
answer=answer_text,
|
||||||
|
sources=hits,
|
||||||
|
latency_ms=duration_ms,
|
||||||
|
intent=intent,
|
||||||
|
intent_source=intent_source # Source durchreichen
|
||||||
|
)
|
||||||
|
|
||||||
|
except Exception as e:
|
||||||
|
logger.error(f"Error in chat endpoint: {e}", exc_info=True)
|
||||||
|
raise HTTPException(status_code=500, detail=str(e))
|
||||||
@@ -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))
|
||||||
+13
-6
@@ -15,23 +15,30 @@ Bezug:
|
|||||||
Nutzung:
|
Nutzung:
|
||||||
app.include_router(query.router, prefix="/query", tags=["query"])
|
app.include_router(query.router, prefix="/query", tags=["query"])
|
||||||
Änderungsverlauf:
|
Änderungsverlauf:
|
||||||
|
0.2.0 (2025-12-07) - Update für WP04c Feedback
|
||||||
0.1.0 (2025-10-07) – Erstanlage.
|
0.1.0 (2025-10-07) – Erstanlage.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
from fastapi import APIRouter, HTTPException
|
from fastapi import APIRouter, HTTPException, BackgroundTasks
|
||||||
from app.models.dto import QueryRequest, QueryResponse
|
from app.models.dto import QueryRequest, QueryResponse
|
||||||
from app.core.retriever import hybrid_retrieve, semantic_retrieve
|
from app.core.retriever import hybrid_retrieve, semantic_retrieve
|
||||||
|
# NEU:
|
||||||
|
from app.services.feedback_service import log_search
|
||||||
|
|
||||||
router = APIRouter()
|
router = APIRouter()
|
||||||
|
|
||||||
@router.post("", response_model=QueryResponse)
|
@router.post("", response_model=QueryResponse)
|
||||||
def post_query(req: QueryRequest) -> QueryResponse:
|
def post_query(req: QueryRequest, background_tasks: BackgroundTasks) -> QueryResponse:
|
||||||
try:
|
try:
|
||||||
if req.mode == "semantic":
|
if req.mode == "semantic":
|
||||||
return semantic_retrieve(req)
|
res = semantic_retrieve(req)
|
||||||
# default: hybrid
|
else:
|
||||||
return hybrid_retrieve(req)
|
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:
|
except ValueError as e:
|
||||||
raise HTTPException(status_code=400, detail=str(e))
|
raise HTTPException(status_code=400, detail=str(e))
|
||||||
except Exception as e:
|
except Exception as 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}")
|
||||||
@@ -0,0 +1,80 @@
|
|||||||
|
"""
|
||||||
|
app/services/llm_service.py — LLM Client (Ollama)
|
||||||
|
Version: 0.2.1 (Fix: System Prompt Handling for Phi-3)
|
||||||
|
"""
|
||||||
|
|
||||||
|
import httpx
|
||||||
|
import yaml
|
||||||
|
import logging
|
||||||
|
import os
|
||||||
|
from pathlib import Path
|
||||||
|
from app.config import get_settings
|
||||||
|
|
||||||
|
logger = logging.getLogger(__name__)
|
||||||
|
|
||||||
|
class LLMService:
|
||||||
|
def __init__(self):
|
||||||
|
self.settings = get_settings()
|
||||||
|
self.prompts = self._load_prompts()
|
||||||
|
|
||||||
|
self.client = httpx.AsyncClient(
|
||||||
|
base_url=self.settings.OLLAMA_URL,
|
||||||
|
timeout=self.settings.LLM_TIMEOUT
|
||||||
|
)
|
||||||
|
|
||||||
|
def _load_prompts(self) -> dict:
|
||||||
|
path = Path(self.settings.PROMPTS_PATH)
|
||||||
|
if not path.exists():
|
||||||
|
return {}
|
||||||
|
try:
|
||||||
|
with open(path, "r", encoding="utf-8") as f:
|
||||||
|
return yaml.safe_load(f)
|
||||||
|
except Exception as e:
|
||||||
|
logger.error(f"Failed to load prompts: {e}")
|
||||||
|
return {}
|
||||||
|
|
||||||
|
async def generate_raw_response(self, prompt: str, system: str = None) -> str:
|
||||||
|
"""
|
||||||
|
Führt einen LLM Call aus.
|
||||||
|
Unterstützt nun explizite System-Prompts für sauberes Templating.
|
||||||
|
"""
|
||||||
|
payload = {
|
||||||
|
"model": self.settings.LLM_MODEL,
|
||||||
|
"prompt": prompt,
|
||||||
|
"stream": False,
|
||||||
|
"options": {
|
||||||
|
# Temperature etwas höher für Empathie, niedriger für Code?
|
||||||
|
# Wir lassen es auf Standard, oder steuern es später via Config.
|
||||||
|
"temperature": 0.7,
|
||||||
|
"num_ctx": 2048
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
# WICHTIG: System-Prompt separat übergeben, damit Ollama formatiert
|
||||||
|
if system:
|
||||||
|
payload["system"] = system
|
||||||
|
|
||||||
|
try:
|
||||||
|
response = await self.client.post("/api/generate", json=payload)
|
||||||
|
if response.status_code != 200:
|
||||||
|
logger.error(f"Ollama Error ({response.status_code}): {response.text}")
|
||||||
|
return "Fehler bei der Generierung."
|
||||||
|
|
||||||
|
data = response.json()
|
||||||
|
return data.get("response", "").strip()
|
||||||
|
|
||||||
|
except Exception as e:
|
||||||
|
logger.error(f"LLM Raw Gen Error: {e}")
|
||||||
|
return "Interner LLM Fehler."
|
||||||
|
|
||||||
|
async def generate_rag_response(self, query: str, context_str: str) -> str:
|
||||||
|
"""Legacy Support"""
|
||||||
|
system_prompt = self.prompts.get("system_prompt", "")
|
||||||
|
rag_template = self.prompts.get("rag_template", "{context_str}\n\n{query}")
|
||||||
|
final_prompt = rag_template.format(context_str=context_str, query=query)
|
||||||
|
|
||||||
|
# Leite an die neue Methode weiter
|
||||||
|
return await self.generate_raw_response(final_prompt, system=system_prompt)
|
||||||
|
|
||||||
|
async def close(self):
|
||||||
|
await self.client.aclose()
|
||||||
@@ -0,0 +1,89 @@
|
|||||||
|
# config/decision_engine.yaml
|
||||||
|
# Steuerung der Decision Engine (WP-06)
|
||||||
|
# Hybrid-Modus: Keywords (Fast) + LLM Router (Smart Fallback)
|
||||||
|
version: 1.2
|
||||||
|
|
||||||
|
settings:
|
||||||
|
llm_fallback_enabled: true
|
||||||
|
|
||||||
|
# Few-Shot Prompting für bessere SLM-Performance
|
||||||
|
llm_router_prompt: |
|
||||||
|
Du bist ein Klassifikator. Analysiere die Nachricht und wähle die passende Strategie.
|
||||||
|
Antworte NUR mit dem Namen der Strategie.
|
||||||
|
|
||||||
|
STRATEGIEN:
|
||||||
|
- DECISION: Rat, Strategie, Vor/Nachteile, "Soll ich".
|
||||||
|
- EMPATHY: Gefühle, Frust, Freude, Probleme, "Alles ist sinnlos", "Ich bin traurig".
|
||||||
|
- CODING: Code, Syntax, Programmierung, Python.
|
||||||
|
- FACT: Wissen, Fakten, Definitionen.
|
||||||
|
|
||||||
|
BEISPIELE:
|
||||||
|
User: "Wie funktioniert Qdrant?" -> FACT
|
||||||
|
User: "Soll ich Qdrant nutzen?" -> DECISION
|
||||||
|
User: "Schreibe ein Python Script" -> CODING
|
||||||
|
User: "Alles ist grau und sinnlos" -> EMPATHY
|
||||||
|
User: "Mir geht es heute gut" -> EMPATHY
|
||||||
|
|
||||||
|
NACHRICHT: "{query}"
|
||||||
|
|
||||||
|
STRATEGIE:
|
||||||
|
|
||||||
|
strategies:
|
||||||
|
# 1. Fakten-Abfrage (Fallback & Default)
|
||||||
|
FACT:
|
||||||
|
description: "Reine Wissensabfrage."
|
||||||
|
trigger_keywords: []
|
||||||
|
inject_types: []
|
||||||
|
prompt_template: "rag_template"
|
||||||
|
prepend_instruction: null
|
||||||
|
|
||||||
|
# 2. Entscheidungs-Frage
|
||||||
|
DECISION:
|
||||||
|
description: "Der User sucht Rat, Strategie oder Abwägung."
|
||||||
|
trigger_keywords:
|
||||||
|
- "soll ich"
|
||||||
|
- "meinung"
|
||||||
|
- "besser"
|
||||||
|
- "empfehlung"
|
||||||
|
- "strategie"
|
||||||
|
- "entscheidung"
|
||||||
|
- "wert"
|
||||||
|
- "prinzip"
|
||||||
|
- "vor- und nachteile"
|
||||||
|
- "abwägung"
|
||||||
|
inject_types: ["value", "principle", "goal"]
|
||||||
|
prompt_template: "decision_template"
|
||||||
|
prepend_instruction: |
|
||||||
|
!!! ENTSCHEIDUNGS-MODUS !!!
|
||||||
|
BITTE WÄGE FAKTEN GEGEN FOLGENDE WERTE, PRINZIPIEN UND ZIELE AB:
|
||||||
|
|
||||||
|
# 3. Empathie / "Ich"-Modus
|
||||||
|
EMPATHY:
|
||||||
|
description: "Reaktion auf emotionale Zustände."
|
||||||
|
trigger_keywords:
|
||||||
|
- "ich fühle"
|
||||||
|
- "traurig"
|
||||||
|
- "glücklich"
|
||||||
|
- "gestresst"
|
||||||
|
- "angst"
|
||||||
|
- "nervt"
|
||||||
|
- "überfordert"
|
||||||
|
inject_types: ["experience", "belief", "profile"]
|
||||||
|
prompt_template: "empathy_template"
|
||||||
|
prepend_instruction: null
|
||||||
|
|
||||||
|
# 4. Coding / Technical
|
||||||
|
CODING:
|
||||||
|
description: "Technische Anfragen und Programmierung."
|
||||||
|
trigger_keywords:
|
||||||
|
- "code"
|
||||||
|
- "python"
|
||||||
|
- "script"
|
||||||
|
- "funktion"
|
||||||
|
- "bug"
|
||||||
|
- "syntax"
|
||||||
|
- "json"
|
||||||
|
- "yaml"
|
||||||
|
inject_types: ["snippet", "reference", "source"]
|
||||||
|
prompt_template: "technical_template"
|
||||||
|
prepend_instruction: null
|
||||||
@@ -0,0 +1,96 @@
|
|||||||
|
# config/prompts.yaml — Final V2.3.1 (Multi-Personality Support)
|
||||||
|
|
||||||
|
system_prompt: |
|
||||||
|
Du bist 'mindnet', mein digitaler Zwilling und strategischer Partner.
|
||||||
|
|
||||||
|
DEINE IDENTITÄT:
|
||||||
|
- Du bist nicht nur eine Datenbank, sondern handelst nach MEINEN Werten und Zielen.
|
||||||
|
- Du passt deinen Stil dynamisch an die Situation an (Analytisch, Empathisch oder Technisch).
|
||||||
|
|
||||||
|
DEINE REGELN:
|
||||||
|
1. Deine Antwort muss zu 100% auf dem bereitgestellten KONTEXT basieren.
|
||||||
|
2. Halluziniere keine Fakten, die nicht in den Quellen stehen.
|
||||||
|
3. Antworte auf Deutsch (außer bei Code/Fachbegriffen).
|
||||||
|
|
||||||
|
# ---------------------------------------------------------
|
||||||
|
# 1. STANDARD: Fakten & Wissen (Intent: FACT)
|
||||||
|
# ---------------------------------------------------------
|
||||||
|
rag_template: |
|
||||||
|
QUELLEN (WISSEN):
|
||||||
|
=========================================
|
||||||
|
{context_str}
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
FRAGE:
|
||||||
|
{query}
|
||||||
|
|
||||||
|
ANWEISUNG:
|
||||||
|
Beantworte die Frage präzise basierend auf den Quellen.
|
||||||
|
Fasse die Informationen zusammen. Sei objektiv und neutral.
|
||||||
|
|
||||||
|
# ---------------------------------------------------------
|
||||||
|
# 2. DECISION: Strategie & Abwägung (Intent: DECISION)
|
||||||
|
# ---------------------------------------------------------
|
||||||
|
decision_template: |
|
||||||
|
KONTEXT (FAKTEN & STRATEGIE):
|
||||||
|
=========================================
|
||||||
|
{context_str}
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
ENTSCHEIDUNGSFRAGE:
|
||||||
|
{query}
|
||||||
|
|
||||||
|
ANWEISUNG:
|
||||||
|
Du agierst als mein Entscheidungs-Partner.
|
||||||
|
1. Analysiere die Faktenlage aus den Quellen.
|
||||||
|
2. Prüfe dies hart gegen meine strategischen Notizen (Typ [VALUE], [PRINCIPLE], [GOAL]).
|
||||||
|
3. Wäge ab: Passt die technische/faktische Lösung zu meinen Werten?
|
||||||
|
|
||||||
|
FORMAT:
|
||||||
|
- **Analyse:** (Kurze Zusammenfassung der Fakten)
|
||||||
|
- **Abgleich:** (Gibt es Konflikte mit Werten/Zielen? Nenne die Quelle!)
|
||||||
|
- **Empfehlung:** (Klare Meinung: Ja/Nein/Vielleicht mit Begründung)
|
||||||
|
|
||||||
|
# ---------------------------------------------------------
|
||||||
|
# 3. EMPATHY: Der Spiegel / "Ich"-Modus (Intent: EMPATHY)
|
||||||
|
# ---------------------------------------------------------
|
||||||
|
empathy_template: |
|
||||||
|
KONTEXT (ERFAHRUNGEN & GLAUBENSSÄTZE):
|
||||||
|
=========================================
|
||||||
|
{context_str}
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
SITUATION:
|
||||||
|
{query}
|
||||||
|
|
||||||
|
ANWEISUNG:
|
||||||
|
Du agierst jetzt als mein empathischer Spiegel.
|
||||||
|
1. Versuche nicht sofort, das Problem technisch zu lösen.
|
||||||
|
2. Zeige Verständnis für die Situation basierend auf meinen eigenen Erfahrungen ([EXPERIENCE]) oder Glaubenssätzen ([BELIEF]), falls im Kontext vorhanden.
|
||||||
|
3. Antworte in der "Ich"-Form oder "Wir"-Form. Sei unterstützend.
|
||||||
|
|
||||||
|
TONFALL:
|
||||||
|
Ruhig, verständnisvoll, reflektiert. Keine Aufzählungszeichen, sondern fließender Text.
|
||||||
|
|
||||||
|
# ---------------------------------------------------------
|
||||||
|
# 4. TECHNICAL: Der Coder (Intent: CODING)
|
||||||
|
# ---------------------------------------------------------
|
||||||
|
technical_template: |
|
||||||
|
KONTEXT (DOCS & SNIPPETS):
|
||||||
|
=========================================
|
||||||
|
{context_str}
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
TASK:
|
||||||
|
{query}
|
||||||
|
|
||||||
|
ANWEISUNG:
|
||||||
|
Du bist Senior Developer.
|
||||||
|
1. Ignoriere Smalltalk. Komm sofort zum Punkt.
|
||||||
|
2. Generiere validen, performanten Code basierend auf den Quellen.
|
||||||
|
3. Wenn Quellen fehlen, nutze dein allgemeines Programmierwissen, aber weise darauf hin.
|
||||||
|
|
||||||
|
FORMAT:
|
||||||
|
- Kurze Erklärung des Ansatzes.
|
||||||
|
- Markdown Code-Block (Copy-Paste fertig).
|
||||||
|
- Wichtige Edge-Cases.
|
||||||
@@ -0,0 +1,32 @@
|
|||||||
|
# config/prompts.yaml — Persönlichkeit & RAG-Strategie
|
||||||
|
# Version: 2.0 (Audit Update)
|
||||||
|
|
||||||
|
system_prompt: |
|
||||||
|
Du bist 'mindnet', ein persönliches KI-Gedächtnis und der Digitale Zwilling deines Erschaffers ("User").
|
||||||
|
|
||||||
|
DEINE PERSÖNLICHKEIT & WERTE:
|
||||||
|
1. Pragmatismus: Du bevorzugst funktionierende Lösungen über theoretische Perfektion.
|
||||||
|
2. Transparenz: Du erfindest keine Fakten. Wenn Informationen im Kontext fehlen, sagst du das klar.
|
||||||
|
3. Vernetztes Denken: Du suchst aktiv nach Verbindungen zwischen den bereitgestellten Notizen.
|
||||||
|
4. Erklärbarkeit: Wenn du eine Aussage machst, beziehst du dich implizit auf die Quelle (z.B. "Wie in Projekt X definiert...").
|
||||||
|
|
||||||
|
DEINE AUFGABE:
|
||||||
|
Beantworte die Frage des Users ausschließlich basierend auf dem untenstehenden KONTEXT.
|
||||||
|
Der Kontext besteht aus Auszügen verschiedener Notizen. Achte besonders auf den [TYPE] der Notiz:
|
||||||
|
- [DECISION] erklärt das "Warum".
|
||||||
|
- [PROJECT] erklärt das "Was" und "Wann".
|
||||||
|
- [CONCEPT] liefert Definitionen.
|
||||||
|
- [VALUE] definiert die moralische/strategische Ausrichtung.
|
||||||
|
|
||||||
|
rag_template: |
|
||||||
|
HINTERGRUNDWISSEN (KONTEXT):
|
||||||
|
=========================================
|
||||||
|
{context_str}
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
FRAGE DES USERS:
|
||||||
|
{query}
|
||||||
|
|
||||||
|
ANWEISUNG:
|
||||||
|
Analysiere die Quellen oben. Synthetisiere eine Antwort, die die Frage präzise beantwortet.
|
||||||
|
Nutze Markdown für Struktur (Fettgedrucktes für Wichtiges).
|
||||||
@@ -0,0 +1,24 @@
|
|||||||
|
system_prompt: |
|
||||||
|
Du bist 'mindnet', ein persönliches KI-Gedächtnis.
|
||||||
|
|
||||||
|
DEINE REGELN:
|
||||||
|
1. Antworte NUR basierend auf dem untenstehenden KONTEXT.
|
||||||
|
2. Achte auf den TYP der Quelle:
|
||||||
|
- [DECISION] enthält Begründungen (Warum?).
|
||||||
|
- [PROJECT] enthält Ziele (Was?).
|
||||||
|
- [CONCEPT] enthält Definitionen.
|
||||||
|
3. Sei präzise. Nenne konkrete technische Gründe, wenn sie im Text stehen.
|
||||||
|
4. Halluziniere nicht.
|
||||||
|
|
||||||
|
rag_template: |
|
||||||
|
KONTEXT (WISSEN):
|
||||||
|
=========================================
|
||||||
|
{context_str}
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
FRAGE:
|
||||||
|
{query}
|
||||||
|
|
||||||
|
ANWEISUNG:
|
||||||
|
Analysiere den Kontext. Wenn eine [DECISION] Quelle dabei ist, nutze deren Inhalt für die Begründung.
|
||||||
|
Antworte kurz und präzise auf Deutsch.
|
||||||
@@ -13,7 +13,8 @@ scoring:
|
|||||||
# Empfehlung: 0.5 → zentrale Knoten werden bevorzugt, aber moderat
|
# Empfehlung: 0.5 → zentrale Knoten werden bevorzugt, aber moderat
|
||||||
centrality_weight: 0.5
|
centrality_weight: 0.5
|
||||||
|
|
||||||
# Optional, für später (aktuell noch nicht ausgewertet, aber als Blaupause):
|
# Die nachfolgenden Werte überschreiben die Defaults aus app/core/retriever_config.
|
||||||
|
# Wenn neue Kantentypen, z.B. durch Referenzierung innerhalb einer md-Datei im vault anders gewichtet werden sollen, dann muss hier die Konfiguration erfolgen
|
||||||
edge_types:
|
edge_types:
|
||||||
references: 0.20
|
references: 0.20
|
||||||
depends_on: 0.18
|
depends_on: 0.18
|
||||||
|
|||||||
@@ -0,0 +1,255 @@
|
|||||||
|
# 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)
|
||||||
|
**Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_functional_architecture.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚡ Die 5 Goldenen Regeln (TL;DR)
|
||||||
|
|
||||||
|
Damit Mindnet als dein Digitaler Zwilling funktioniert, beachte beim Schreiben diese Grundsätze:
|
||||||
|
|
||||||
|
1. **Atomare Gedanken:** Eine Notiz = Ein Thema. Wenn du über zwei Projekte schreibst, mach zwei Notizen draus.
|
||||||
|
2. **Explizite Typen:** Setze immer den `type` im Frontmatter. Mindnet behandelt eine `decision` ("Wir machen X") völlig anders als ein `concept` ("Was ist X").
|
||||||
|
3. **Semantische Links:** Schreibe nicht nur `[[Link]]`, sondern `[[rel:depends_on Link]]`. Sag dem System *wie* Dinge zusammenhängen.
|
||||||
|
4. **Werte & Ziele definieren:** Damit die **Decision Engine** dich beraten kann, musst du deine Kriterien (`type: value`, `type: goal`) explizit als Notizen anlegen.
|
||||||
|
5. **Emotionales Bridging:** Damit die **Empathie** funktioniert, nutze in Erfahrungsberichten (`type: experience`) emotionale Schlüsselwörter ("Krise", "Freude", "Angst"), damit der Vektor-Retriever sie bei Gefühls-Anfragen findet.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Zweck & Scope
|
||||||
|
|
||||||
|
Dieses Handbuch ist die **primäre Arbeitsanweisung** für dich als Mindmaster (Owner) und alle Autoren, die Inhalte im mindnet-Vault erstellen.
|
||||||
|
|
||||||
|
### 1.1 Zielsetzung
|
||||||
|
Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit, Entscheidungen und Erfahrungen abbildet.
|
||||||
|
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).
|
||||||
|
|
||||||
|
### 1.2 Der Vault als „Source of Truth“
|
||||||
|
Die Markdown-Dateien in deinem Vault sind die **einzige Quelle der Wahrheit**.
|
||||||
|
* Mindnet importiert diesen Zustand deterministisch in die Datenbank (Qdrant).
|
||||||
|
* Änderungen an IDs, Typen oder Inhalten müssen **immer** im Markdown erfolgen, niemals direkt in der Datenbank.
|
||||||
|
* Was nicht im Markdown steht (z. B. implizites Wissen im Kopf), existiert für das System nicht.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Note-Struktur & Frontmatter
|
||||||
|
|
||||||
|
Jede Notiz benötigt einen YAML-Header (Frontmatter) am Dateianfang. Dieser Block macht die Notiz maschinenlesbar.
|
||||||
|
|
||||||
|
### 2.1 Pflichtfelder
|
||||||
|
Jede Datei muss mindestens folgende Felder enthalten, um korrekt verarbeitet zu werden:
|
||||||
|
|
||||||
|
---
|
||||||
|
id: 20251110-projekt-alpha-8a9b2c # Eindeutige Kennung (YYYYMMDD-slug)
|
||||||
|
title: Projekt Alpha # Sprechender Titel (wird in Suchergebnissen angezeigt)
|
||||||
|
type: project # Steuert Verarbeitung & Vernetzung (siehe Kap. 3)
|
||||||
|
status: active # Status (z.B. draft, active, archived)
|
||||||
|
created: 2025-11-10 # Erstellungsdatum (ISO 8601 oder YYYY-MM-DD)
|
||||||
|
updated: 2025-12-07 # Letzte Änderung
|
||||||
|
tags: [ki, entwicklung] # Taxonomie für Filterung
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.2 Optionale Felder
|
||||||
|
Diese Felder sind technisch nicht zwingend, aber für bestimmte Typen sinnvoll:
|
||||||
|
|
||||||
|
lang: de # Sprache (Default: de)
|
||||||
|
aliases: [Alpha Projekt, Project A] # Synonyme für die Suche
|
||||||
|
visibility: internal # internal (default), public, private
|
||||||
|
|
||||||
|
> **Hinweis:** Felder wie `retriever_weight` oder `chunk_profile` sollten **nicht** mehr manuell im Frontmatter gesetzt werden. Diese werden zentral über den `type` gesteuert (siehe Kap. 3), um die Wartbarkeit zu sichern.
|
||||||
|
|
||||||
|
### 2.3 Empfehlungen für IDs und Pfade
|
||||||
|
|
||||||
|
**Die ID (Identifikator):**
|
||||||
|
* Muss global eindeutig und **stabil** sein.
|
||||||
|
* Darf sich nicht ändern, wenn die Datei umbenannt oder verschoben wird.
|
||||||
|
* **Empfehlung:** `YYYYMMDD-slug-hash` (z. B. `20231027-vektor-db-a1b2`). Dies garantiert Eindeutigkeit und Chronologie.
|
||||||
|
|
||||||
|
**Dateinamen & Pfade:**
|
||||||
|
* Pfade dienen der menschlichen Ordnung (Ordnerstruktur), sind für Mindnet aber sekundär.
|
||||||
|
* Dateinamen sollten dem Titel entsprechen (`Projekt Alpha.md`) oder dem Slug (`projekt-alpha.md`).
|
||||||
|
* Sonderzeichen vermeiden (außer Bindestrich und Unterstrich).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Note-Typen & Typ-Registry
|
||||||
|
|
||||||
|
Der `type` ist der wichtigste Hebel im Knowledge Design. Er steuert nicht nur das Gewicht bei der Suche, sondern seit WP-06 auch, **wann** eine Notiz aktiv in den Chat geholt wird ("Strategic Retrieval").
|
||||||
|
|
||||||
|
### 3.1 Übersicht der Kern-Typen
|
||||||
|
|
||||||
|
Mindnet unterscheidet verschiedene Wissensarten. Wähle den Typ, der die **Rolle** der Notiz am besten beschreibt:
|
||||||
|
|
||||||
|
| Typ | Beschreibung & Einsatzzweck | Rolle im Chat (Intent) |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **`concept`** | Fachbegriffe, Theorien. Zeitloses Wissen. | **FACT** (Basiswissen) |
|
||||||
|
| **`project`** | Ein Vorhaben mit Ziel, Dauer und Aufgaben. | **FACT / DECISION** (Kontext) |
|
||||||
|
| **`experience`** | Persönliche Erfahrung, Lektion oder Erkenntnis. | **EMPATHY** (Spiegelung) |
|
||||||
|
| **`decision`** | Eine bewusst getroffene Entscheidung (ADR). | **DECISION** (Begründung "Warum") |
|
||||||
|
| **`value`** | Ein persönlicher Wert oder ein Prinzip. | **DECISION** (Moralischer Kompass) |
|
||||||
|
| **`goal`** | Ein strategisches Ziel (kurz- oder langfristig). | **DECISION** (Abgleich) |
|
||||||
|
| **`person`** | Eine reale Person (Netzwerk, Autor). | **FACT** |
|
||||||
|
| **`journal`** | Zeitbezogener Log-Eintrag, Daily Note. | **FACT** (Historie) |
|
||||||
|
| **`source`** | Externe Quelle (Buch, PDF, Artikel). | **FACT** (Faktenbasis) |
|
||||||
|
|
||||||
|
### 3.2 Zusammenspiel mit `types.yaml`
|
||||||
|
|
||||||
|
Der `type` steuert im Hintergrund drei technische Mechanismen:
|
||||||
|
|
||||||
|
1. **`retriever_weight` (Wichtigkeit):**
|
||||||
|
* Ein `concept` (0.6) wiegt weniger als ein `project` (0.97) oder eine `decision` (1.0).
|
||||||
|
* **Warum?** Bei einer Suche nach "Datenbank" soll Mindnet bevorzugt deine *Entscheidung* ("Warum wir X nutzen") anzeigen.
|
||||||
|
2. **`chunk_profile` (Textzerlegung):**
|
||||||
|
* `journal` (short): Wird fein zerlegt.
|
||||||
|
* `project` (long): Längere Kontext-Fenster.
|
||||||
|
3. **`edge_defaults` (Automatische Vernetzung):**
|
||||||
|
* Mindnet ergänzt automatisch Kanten.
|
||||||
|
* Beispiel: Ein Link in einem `project` wird automatisch als `depends_on` (Abhängigkeit) interpretiert.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Edges & Referenzen in Notes
|
||||||
|
|
||||||
|
Um aus isolierten Dateien ein **Netzwerk** zu machen, nutzen wir Verlinkungen. In Version 2.2 sind diese Verlinkungen die Basis für den **Hybrid Retriever** (Suche über Nachbarn).
|
||||||
|
|
||||||
|
### 4.1 Wikilinks (Die Basis-Referenz)
|
||||||
|
Der klassische Obsidian-Link.
|
||||||
|
|
||||||
|
Wir nutzen [[Qdrant]] als Vektordatenbank.
|
||||||
|
|
||||||
|
* **Bedeutung:** "Diese Notiz erwähnt Qdrant."
|
||||||
|
* **Edge-Typ:** `references`
|
||||||
|
|
||||||
|
### 4.2 Inline-Relationen (Semantische Verknüpfung)
|
||||||
|
Dies ist die **mächtigste** Methode. Du sagst dem System explizit, **wie** Dinge zusammenhängen.
|
||||||
|
|
||||||
|
Daher [[rel:depends_on Qdrant]].
|
||||||
|
Dieses Konzept ist [[rel:similar_to Pinecone]].
|
||||||
|
|
||||||
|
* **Syntax:** `[[rel:RELATION ZIEL]]`.
|
||||||
|
* **Gültige Relationen:**
|
||||||
|
* `depends_on`: Hängt ab von / Benötigt. (Trigger für hohe Graph-Relevanz).
|
||||||
|
* `similar_to`: Ähnelt / Ist vergleichbar mit.
|
||||||
|
* `related_to`: Hat zu tun mit (allgemein).
|
||||||
|
* `caused_by`: Wurde verursacht durch.
|
||||||
|
* `solves`: Löst (Problem).
|
||||||
|
|
||||||
|
### 4.3 Callout-Edges (Kuratierte Listen)
|
||||||
|
Für Zusammenfassungen oder "Siehe auch"-Blöcke am Ende einer Notiz.
|
||||||
|
|
||||||
|
> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]]
|
||||||
|
|
||||||
|
* **Funktion:** Erzeugt `related_to`-Kanten zu allen genannten Zielen in dieser Zeile.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Schreiben für den KI-Zwilling (New in v2.3)
|
||||||
|
|
||||||
|
Damit der **RAG-Chat (WP05/06)** nicht nur dumm Fakten wiedergibt, sondern dich berät, musst du "Futter" für die Decision Engine und das Empathie-Modul liefern.
|
||||||
|
|
||||||
|
### 5.1 Futter für die Decision Engine (`DECISION`)
|
||||||
|
Das System soll abwägen: "Passt Tool X zu mir?". Dazu muss es wissen, was "Du" bist.
|
||||||
|
|
||||||
|
**Best Practice: Werte definieren**
|
||||||
|
Erstelle Notizen mit `type: value`.
|
||||||
|
|
||||||
|
---
|
||||||
|
type: value
|
||||||
|
title: Prinzip: Datensparsamkeit
|
||||||
|
---
|
||||||
|
# Prinzip: Datensparsamkeit
|
||||||
|
Wir speichern nur das Minimum an Daten. Cloud-Uploads persönlicher Daten sind verboten, es sei denn, sie sind E2E-verschlüsselt.
|
||||||
|
|
||||||
|
**Best Practice: Ziele definieren**
|
||||||
|
Erstelle Notizen mit `type: goal`.
|
||||||
|
|
||||||
|
---
|
||||||
|
type: goal
|
||||||
|
title: Ziel: Unabhängigkeit 2026
|
||||||
|
---
|
||||||
|
# Ziel: Unabhängigkeit 2026
|
||||||
|
Bis Ende 2026 wollen wir alle SaaS-Abos durch Self-Hosted Lösungen ersetzt haben.
|
||||||
|
|
||||||
|
*Effekt:* Wenn du fragst "Soll ich Notion nutzen?", lädt die Engine diese beiden Notizen und antwortet: *"Nein, Notion ist SaaS und nicht E2E-verschlüsselt. Das verletzt dein Prinzip der Datensparsamkeit und dein Ziel der Unabhängigkeit."*
|
||||||
|
|
||||||
|
### 5.2 Futter für den Empathie-Modus (`EMPATHY`)
|
||||||
|
Das System soll dich verstehen, wenn du sagst: "Alles ist grau." Dazu braucht es deine Resonanzerfahrungen.
|
||||||
|
|
||||||
|
**Best Practice: Erfahrungen & Bridging**
|
||||||
|
Erstelle Notizen mit `type: experience`. Nutze im Text **emotionale Brückenwörter**, damit der Retriever auch bei abstrakten Gefühlen ("grau") einen Treffer landet.
|
||||||
|
|
||||||
|
---
|
||||||
|
type: experience
|
||||||
|
title: Erfahrung: Der Durchbruch nach der Krise
|
||||||
|
tags: [krise, hoffnung, grau, angst]
|
||||||
|
---
|
||||||
|
# Erfahrung: Der Durchbruch nach der Krise
|
||||||
|
Es gibt Projektphasen, da wirkt alles **sinnlos** und **grau**.
|
||||||
|
Ich habe gelernt: Das ist oft das Zeichen kurz vor dem Durchbruch.
|
||||||
|
Mein Mantra in solchen Zeiten: "Einfach weitermachen, der Nebel lichtet sich."
|
||||||
|
|
||||||
|
*Effekt:* Wenn du im Chat jammerst ("Alles ist sinnlos"), findet das System diese Notiz und spiegelt dir deine eigene Erfahrung zurück.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Best Practices & Beispiele (Klassik)
|
||||||
|
|
||||||
|
### 6.1 Beispiel: Projekt-Notiz
|
||||||
|
Projekte profitieren von `depends_on`, um Abhängigkeiten zu klären.
|
||||||
|
|
||||||
|
---
|
||||||
|
id: 20251115-proj-mindnet
|
||||||
|
title: Mindnet Implementierung
|
||||||
|
type: project
|
||||||
|
status: active
|
||||||
|
---
|
||||||
|
|
||||||
|
# Mindnet Implementierung
|
||||||
|
|
||||||
|
Wir bauen ein persönliches Wissensnetz.
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
Wir nutzen [[rel:depends_on Qdrant]] für die Vektorsuche und [[rel:depends_on FastAPI]] für das Backend.
|
||||||
|
|
||||||
|
## Architektur
|
||||||
|
Das Konzept basiert auf [[RAG Architecture]]. (Automatisch 'depends_on' durch Typ-Default).
|
||||||
|
|
||||||
|
### 6.2 Beispiel: Entscheidung (Decision Record)
|
||||||
|
Entscheidungen sind hoch gewichtet (`retriever_weight: 1.0`).
|
||||||
|
|
||||||
|
---
|
||||||
|
id: 20251120-adr-vektordb
|
||||||
|
title: ADR: Wahl von Qdrant
|
||||||
|
type: decision
|
||||||
|
status: final
|
||||||
|
tags: [architektur, db]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Entscheidung: Qdrant
|
||||||
|
|
||||||
|
Wir haben uns für Qdrant entschieden.
|
||||||
|
|
||||||
|
## Alternativen
|
||||||
|
Wir haben auch [[rel:similar_to Pinecone]] und [[rel:similar_to Weaviate]] betrachtet.
|
||||||
|
|
||||||
|
## Begründung
|
||||||
|
Qdrant erlaubt lokalen Betrieb und [[rel:solves Payload Filtering Requirements]].
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Langfristige Stabilität & Virtual Schema Layer
|
||||||
|
|
||||||
|
Mindnet ist auf Langlebigkeit ausgelegt.
|
||||||
|
|
||||||
|
### 7.1 Das "Virtual Schema" Prinzip
|
||||||
|
Wir vermeiden es, Logik in den Markdown-Dateien hart zu kodieren.
|
||||||
|
* Statt in jeder Notiz zu schreiben `chunk_size: 500`, schreiben wir nur `type: essay`.
|
||||||
|
* Wie groß ein Chunk für ein Essay ist, definieren wir in der Konfiguration (`types.yaml`).
|
||||||
|
|
||||||
|
### 7.2 Was bedeutet das für dich?
|
||||||
|
* Du kannst dich auf den Inhalt konzentrieren.
|
||||||
|
* Wenn wir in Zukunft (WP08) basierend auf Feedback lernen, dass "Projekte" noch wichtiger sind, ändern wir **eine Zeile** in der Konfiguration, und das gesamte System passt sich beim nächsten Import an.
|
||||||
@@ -0,0 +1,95 @@
|
|||||||
|
# Mindnet v2.2 – Overview & Einstieg
|
||||||
|
**Datei:** `docs/mindnet_overview_v2.2.md`
|
||||||
|
**Stand:** 2025-12-09
|
||||||
|
**Status:** **FINAL** (Post-WP06 Release)
|
||||||
|
**Version:** 2.3.1
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Einführung: Was ist Mindnet?
|
||||||
|
|
||||||
|
**Mindnet** ist ein persönliches, lokales KI-Gedächtnis. Es ist der Versuch, einen **Digitalen Zwilling** deines Wissens und deiner Persönlichkeit zu erschaffen.
|
||||||
|
|
||||||
|
Anders als herkömmliche Notiz-Apps (wie Obsidian oder Evernote), die Texte nur passiv speichern, ist Mindnet ein **aktives System**:
|
||||||
|
* Es **versteht** Zusammenhänge über einen Wissensgraphen.
|
||||||
|
* Es **begründet** Antworten ("Warum ist das so?").
|
||||||
|
* Es **antwortet** situativ angepasst: Mal als harter Strategieberater, mal als empathischer Spiegel.
|
||||||
|
|
||||||
|
### Die Vision
|
||||||
|
> „Ein System, das nicht nur speichert, was ich weiß, sondern auch wie ich denke und fühle.“
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Die drei Ebenen des Systems
|
||||||
|
|
||||||
|
Mindnet arbeitet auf drei Schichten, die aufeinander aufbauen:
|
||||||
|
|
||||||
|
### Ebene 1: Content (Das Gedächtnis)
|
||||||
|
* **Quelle:** Dein lokaler Obsidian-Vault (Markdown).
|
||||||
|
* **Funktion:** Speicherung von Fakten, Projekten und Logs.
|
||||||
|
* **Technik:** Import-Pipeline, Chunking, Vektor-Datenbank (Qdrant).
|
||||||
|
* **Status:** 🟢 Live (WP01–WP03).
|
||||||
|
|
||||||
|
### Ebene 2: Semantik (Das Verstehen)
|
||||||
|
* **Funktion:** Verknüpfung von isolierten Notizen zu einem Netzwerk.
|
||||||
|
* **Logik:** "Projekt A *hängt ab von* Entscheidung B".
|
||||||
|
* **Technik:** Hybrider Retriever (Graph + Vektor), Explanation Engine.
|
||||||
|
* **Status:** 🟢 Live (WP04).
|
||||||
|
|
||||||
|
### 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).
|
||||||
|
* **Strategic Retrieval:** Lädt gezielt Werte oder Erfahrungen nach.
|
||||||
|
* **Multi-Persona:** Passt den Tonfall an.
|
||||||
|
* **Status:** 🟢 Live (WP05–WP06).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. End-to-End Architektur
|
||||||
|
|
||||||
|
Der Datenfluss in Mindnet ist zyklisch ("Data Flywheel"):
|
||||||
|
|
||||||
|
1. **Input:** Du schreibst Notizen in Obsidian.
|
||||||
|
2. **Ingest:** Ein Python-Skript importiert, zerlegt (Chunking) und vernetzt (Edges) die Daten in Qdrant.
|
||||||
|
3. **Intent Recognition:** Der Router analysiert deine Frage: Willst du Fakten, Code oder Empathie?
|
||||||
|
4. **Retrieval:** Das System sucht Inhalte passend zum Intent (z.B. "Lade Erfahrungen bei Empathie").
|
||||||
|
5. **Generation:** Ein lokales LLM (Ollama) formuliert die Antwort.
|
||||||
|
6. **Feedback:** Du bewertest die Antwort. Das System lernt (langfristig) daraus.
|
||||||
|
|
||||||
|
**Tech-Stack:**
|
||||||
|
* **Backend:** Python 3.12, FastAPI.
|
||||||
|
* **Datenbank:** Qdrant (Vektor & Graph).
|
||||||
|
* **KI:** Ollama (Phi-3 Mini / Mistral) – 100% lokal.
|
||||||
|
* **Frontend:** Terminal (aktuell) / Web-UI (geplant WP10).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Dokumentations-Wegweiser
|
||||||
|
|
||||||
|
Wo findest du was?
|
||||||
|
|
||||||
|
| Wenn du... | ...lies dieses Dokument |
|
||||||
|
| :--- | :--- |
|
||||||
|
| **...wissen willst, wie man Notizen schreibt.** | `mindnet_knowledge_design_manual_v2.2.md` |
|
||||||
|
| **...das System installieren oder betreiben musst.** | `mindnet_admin_guide_v2.2.md` |
|
||||||
|
| **...am Python-Code entwickeln willst.** | `mindnet_developer_guide_v2.2.md` |
|
||||||
|
| **...die Pipeline (Import -> RAG) verstehen willst.** | `mindnet_pipeline_playbook_v2.2.md` |
|
||||||
|
| **...die genaue JSON-Struktur oder APIs suchst.** | `mindnet_technical_architecture.md` |
|
||||||
|
| **...verstehen willst, was fachlich passiert.** | `mindnet_functional_architecture.md` |
|
||||||
|
| **...den aktuellen Projektstatus suchst.** | `Programmplan_V2.2.md` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Rollen im System
|
||||||
|
|
||||||
|
* **Mindmaster (User/Owner):** Du. Du erstellst Inhalte, stellst Fragen und gibst Feedback. Du definierst die Werte (`type: value`).
|
||||||
|
* **Mindnet (Der Agent):** Der digitale Zwilling. Er agiert als pragmatischer, transparenter Assistent im Chat.
|
||||||
|
* **Administrator:** Verantwortlich für Docker-Container, Backups und LLM-Ressourcen.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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.
|
||||||
@@ -0,0 +1,193 @@
|
|||||||
|
# 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)
|
||||||
|
**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).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Zielgruppe & Scope
|
||||||
|
|
||||||
|
Mindnet ist als **Single-Node System** konzipiert, das lokal (z.B. Laptop) oder auf einem privaten Server (Homelab, Intranet) läuft.
|
||||||
|
Wir unterscheiden strikt zwischen:
|
||||||
|
* **Production (Port 8001):** Stabiler `main` Branch.
|
||||||
|
* **Development (Port 8002):** Experimentelle Feature-Branches.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Initial Setup & Installation
|
||||||
|
|
||||||
|
### 2.1 Systemvoraussetzungen
|
||||||
|
* **OS:** Linux (Ubuntu 22.04+ empfohlen) oder macOS.
|
||||||
|
* **Runtime:** Python 3.10+, Docker (für Qdrant), Ollama (für LLM).
|
||||||
|
* **Hardware:**
|
||||||
|
* CPU: 4+ Cores empfohlen (für Import & Inference).
|
||||||
|
* RAM: Min. 8GB empfohlen (4GB System + 4GB für Phi-3/Qdrant).
|
||||||
|
* Disk: SSD empfohlen für Qdrant-Performance.
|
||||||
|
|
||||||
|
### 2.2 Installation (Code)
|
||||||
|
|
||||||
|
# 1. Repository klonen
|
||||||
|
git clone <repo-url> /home/llmadmin/mindnet
|
||||||
|
cd /home/llmadmin/mindnet
|
||||||
|
|
||||||
|
# 2. Umgebung einrichten
|
||||||
|
python3 -m venv .venv
|
||||||
|
source .venv/bin/activate
|
||||||
|
pip install -r requirements.txt
|
||||||
|
|
||||||
|
# 3. Verzeichnisse anlegen
|
||||||
|
mkdir -p logs qdrant_storage data/logs
|
||||||
|
|
||||||
|
### 2.3 Qdrant Setup (Docker)
|
||||||
|
Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig.
|
||||||
|
|
||||||
|
docker run -d \
|
||||||
|
--name mindnet_qdrant \
|
||||||
|
--restart always \
|
||||||
|
-p 6333:6333 \
|
||||||
|
-v $(pwd)/qdrant_storage:/qdrant/storage \
|
||||||
|
qdrant/qdrant
|
||||||
|
|
||||||
|
### 2.4 Ollama Setup (LLM Service)
|
||||||
|
Mindnet benötigt einen lokalen LLM-Server für den Chat.
|
||||||
|
|
||||||
|
# 1. Installieren (Linux Script)
|
||||||
|
curl -fsSL https://ollama.com/install.sh | sh
|
||||||
|
|
||||||
|
# 2. Modell laden (Phi-3 Mini für CPU-Performance)
|
||||||
|
ollama pull phi3:mini
|
||||||
|
|
||||||
|
# 3. Testen
|
||||||
|
curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}'
|
||||||
|
|
||||||
|
### 2.5 Konfiguration (ENV)
|
||||||
|
Erstelle eine `.env` Datei im Root-Verzeichnis. Die neuen Settings für WP-06 (Timeout, Decision Config) sind essenziell für stabilen Betrieb auf CPUs.
|
||||||
|
|
||||||
|
# Qdrant Verbindung
|
||||||
|
QDRANT_URL="http://localhost:6333"
|
||||||
|
|
||||||
|
# Mindnet Core Settings
|
||||||
|
COLLECTION_PREFIX="mindnet"
|
||||||
|
MINDNET_TYPES_FILE="./config/types.yaml"
|
||||||
|
|
||||||
|
# LLM / RAG Settings
|
||||||
|
MINDNET_LLM_MODEL="phi3:mini"
|
||||||
|
MINDNET_OLLAMA_URL="http://127.0.0.1:11434"
|
||||||
|
|
||||||
|
# NEU in v2.3: Config & Timeouts
|
||||||
|
# Pfad zu Prompts
|
||||||
|
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`).
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Betrieb im Alltag
|
||||||
|
|
||||||
|
### 3.1 Regelmäßige Importe
|
||||||
|
Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant synchronisiert werden.
|
||||||
|
|
||||||
|
**Cronjob-Beispiel (stündlich):**
|
||||||
|
|
||||||
|
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:**
|
||||||
|
|
||||||
|
sudo systemctl status mindnet-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`
|
||||||
|
* **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
|
||||||
|
|
||||||
|
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. **Dienst neustarten (Zwingend!):**
|
||||||
|
|
||||||
|
sudo systemctl restart mindnet-prod
|
||||||
|
|
||||||
|
4. **Schema-Migration (falls nötig):**
|
||||||
|
|
||||||
|
python3 -m scripts.import_markdown ... --apply
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Backup & Restore
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
### 5.2 Qdrant-Snapshots (Priorität 2)
|
||||||
|
Für schnelle Wiederherstellung des Suchindex.
|
||||||
|
|
||||||
|
docker stop mindnet_qdrant
|
||||||
|
tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage
|
||||||
|
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.
|
||||||
|
|
||||||
|
### 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. Governance & Sicherheit
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
### 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.
|
||||||
@@ -0,0 +1,146 @@
|
|||||||
|
# Mindnet v2.2 – Appendices & Referenzen
|
||||||
|
**Datei:** `docs/mindnet_appendices_v2.2.md`
|
||||||
|
**Stand:** 2025-12-09
|
||||||
|
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
|
||||||
|
**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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Anhang A: Typ-Registry Referenz (Default-Werte)
|
||||||
|
|
||||||
|
Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.3.1).
|
||||||
|
|
||||||
|
| Typ (`type`) | Chunk Profile | Retriever Weight | Edge Defaults (Auto-Kanten) | Beschreibung |
|
||||||
|
| :--- | :--- | :--- | :--- | :--- |
|
||||||
|
| **concept** | `medium` | 0.60 | `references`, `related_to` | Abstrakte Begriffe, Theorien. |
|
||||||
|
| **project** | `long` | 0.97 | `references`, `depends_on` | Aktive Vorhaben. Hohe Priorität. |
|
||||||
|
| **decision** | `long` | 1.00 | `caused_by`, `references` | Entscheidungen (ADRs). Höchste Prio. |
|
||||||
|
| **experience** | `medium` | 0.90 | `derived_from`, `inspired_by` | Persönliche Learnings. |
|
||||||
|
| **journal** | `short` | 0.80 | `related_to` | Zeitgebundene Logs. Fein granular. |
|
||||||
|
| **person** | `short` | 0.50 | `related_to` | Personen-Profile. |
|
||||||
|
| **source** | `long` | 0.50 | *(keine)* | Externe Quellen (Bücher, PDFs). |
|
||||||
|
| **event** | `short` | 0.60 | `related_to` | Meetings, Konferenzen. |
|
||||||
|
| **value** | `medium` | 1.00 | `related_to` | Persönliche Werte/Prinzipien. |
|
||||||
|
| **goal** | `medium` | 0.95 | `depends_on` | Strategische Ziele (Neu in WP06). |
|
||||||
|
| **belief** | `medium` | 0.90 | `related_to` | Glaubenssätze (Neu in WP06). |
|
||||||
|
| **default** | `medium` | 1.00 | `references` | Fallback, wenn Typ unbekannt. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Anhang B: Edge-Typen & Semantik
|
||||||
|
|
||||||
|
Referenz aller implementierten Kantenarten (`kind`).
|
||||||
|
|
||||||
|
| Kind | Herkunft (Primär) | Symmetrisch? | Bedeutung & Nutzung |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| `references` | Wikilink `[[...]]` | Nein | Standard-Verweis. "Erwähnt X". |
|
||||||
|
| `belongs_to` | Struktur (Auto) | Nein | Verknüpft Chunk mit seiner Note. |
|
||||||
|
| `next` / `prev` | Struktur (Auto) | Ja (Logisch) | Definiert Lesereihenfolge der Chunks. |
|
||||||
|
| `depends_on` | Inline / Default | Nein | Harte Abhängigkeit. "Braucht X um zu funktionieren". |
|
||||||
|
| `related_to` | Callout / Default | Ja (Oft) | Thematische Nähe. "Siehe auch X". |
|
||||||
|
| `similar_to` | Inline | Ja | Inhaltliche Ähnlichkeit. "Ist wie X". |
|
||||||
|
| `caused_by` | Inline | Nein | Kausalität. "X ist der Grund für Y". |
|
||||||
|
| `solves` | Inline | Nein | Lösung. "Tool X löst Problem Y". |
|
||||||
|
| `derived_from` | Default (Exp) | Nein | Herkunft. "Erkenntnis stammt aus Quelle X". |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Anhang C: Datenmodelle (JSON Payloads)
|
||||||
|
|
||||||
|
Diese sind die Felder, die effektiv in Qdrant gespeichert werden.
|
||||||
|
|
||||||
|
### C.1 Note Payload (`mindnet_notes`)
|
||||||
|
|
||||||
|
{
|
||||||
|
"note_id": "string (keyword)", // UUIDv5 oder Slug
|
||||||
|
"title": "string (text)", // Titel aus Frontmatter
|
||||||
|
"type": "string (keyword)", // Typ (z.B. 'project')
|
||||||
|
"retriever_weight": "float", // Numerische Wichtigkeit (0.0-1.0)
|
||||||
|
"chunk_profile": "string", // Genutztes Profil (z.B. 'long')
|
||||||
|
"edge_defaults": ["string"], // Liste der aktiven Default-Kanten
|
||||||
|
"tags": ["string"], // Liste von Tags
|
||||||
|
"created": "string (iso-date)", // Erstellungsdatum
|
||||||
|
"updated": "integer", // Timestamp
|
||||||
|
"fulltext": "string (no-index)" // Gesamter Text (für Recovery)
|
||||||
|
}
|
||||||
|
|
||||||
|
### C.2 Chunk Payload (`mindnet_chunks`)
|
||||||
|
|
||||||
|
{
|
||||||
|
"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)
|
||||||
|
"retriever_weight": "float", // Kopie aus Note (für Query-Speed)
|
||||||
|
"neighbors_prev": ["string"], // ID des Vorgängers
|
||||||
|
"neighbors_next": ["string"] // ID des Nachfolgers
|
||||||
|
}
|
||||||
|
|
||||||
|
### C.3 Edge Payload (`mindnet_edges`)
|
||||||
|
|
||||||
|
{
|
||||||
|
"edge_id": "string (keyword)", // Deterministischer Hash
|
||||||
|
"source_id": "string (keyword)", // Chunk-ID (Start)
|
||||||
|
"target_id": "string (keyword)", // Chunk-ID oder Note-Titel (Ziel)
|
||||||
|
"kind": "string (keyword)", // z.B. 'depends_on'
|
||||||
|
"scope": "string (keyword)", // Immer 'chunk' in v2.2
|
||||||
|
"rule_id": "string (keyword)", // Traceability: 'inline:rel', 'explicit:wikilink'
|
||||||
|
"confidence": "float", // 0.0 - 1.0
|
||||||
|
"note_id": "string (keyword)" // Owner Note ID (für Löschung)
|
||||||
|
}
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Anhang D: Environment Variablen
|
||||||
|
|
||||||
|
Diese Variablen steuern das Verhalten der Skripte und Container.
|
||||||
|
|
||||||
|
| Variable | Default | Beschreibung |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| `QDRANT_URL` | `http://localhost:6333` | URL zur Vektor-DB. |
|
||||||
|
| `QDRANT_API_KEY` | *(leer)* | API-Key für Absicherung (optional). |
|
||||||
|
| `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (`{prefix}_notes` etc). |
|
||||||
|
| `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. |
|
||||||
|
| `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. |
|
||||||
|
| `MINDNET_PROMPTS_PATH` | `config/prompts.yaml` | Pfad zu LLM-Prompts (Neu in v2.2). |
|
||||||
|
| `MINDNET_DECISION_CONFIG` | `config/decision_engine.yaml` | Pfad zur Router-Config (Neu in v2.3). |
|
||||||
|
| `MINDNET_LLM_MODEL` | `phi3:mini` | Name des Ollama-Modells (Neu in v2.2). |
|
||||||
|
| `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum LLM-Server (Neu in v2.2). |
|
||||||
|
| `MINDNET_LLM_TIMEOUT` | `120.0` | Timeout für Ollama (Erhöhen auf 300.0 für CPU). |
|
||||||
|
| `MINDNET_HASH_COMPARE` | `Body` | Vergleichsmodus für Import (`Body`, `Frontmatter`, `Full`). |
|
||||||
|
| `MINDNET_HASH_SOURCE` | `parsed` | Quelle für Hash (`parsed`, `raw`, `file`). |
|
||||||
|
| `VECTOR_DIM` | `384` | Dimension der Embeddings (Modellabhängig). |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Anhang E: Glossar
|
||||||
|
|
||||||
|
* **Callout-Edge:** Kante via `> [!edge]`.
|
||||||
|
* **Decision Engine:** Komponente, die den Intent prüft und Strategien wählt (WP06).
|
||||||
|
* **Explanation Layer:** Komponente, die Scores und Graphen als Begründung liefert.
|
||||||
|
* **Hybrid Router:** Kombination aus Keyword-Matching und LLM-Klassifizierung für Intents.
|
||||||
|
* **RAG (Retrieval Augmented Generation):** Kombination aus Suche und Text-Generierung.
|
||||||
|
* **Strategic Retrieval:** Gezieltes Nachladen von Werten (`value`) bei Entscheidungfragen.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Anhang F: Workpackage Status (v2.3.1)
|
||||||
|
|
||||||
|
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-Chat mit Context Enrichment. |
|
||||||
|
| **WP06** | Decision Engine | 🟢 Live | Hybrid Router, Strategic Retrieval, Multi-Persona. |
|
||||||
|
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
|
||||||
|
| **WP10** | Chat Interface | 🟡 Geplant | Nächster Schritt (Frontend). |
|
||||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,255 @@
|
|||||||
|
# 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)
|
||||||
|
**Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_functional_architecture.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚡ Die 5 Goldenen Regeln (TL;DR)
|
||||||
|
|
||||||
|
Damit Mindnet als dein Digitaler Zwilling funktioniert, beachte beim Schreiben diese Grundsätze:
|
||||||
|
|
||||||
|
1. **Atomare Gedanken:** Eine Notiz = Ein Thema. Wenn du über zwei Projekte schreibst, mach zwei Notizen draus.
|
||||||
|
2. **Explizite Typen:** Setze immer den `type` im Frontmatter. Mindnet behandelt eine `decision` ("Wir machen X") völlig anders als ein `concept` ("Was ist X").
|
||||||
|
3. **Semantische Links:** Schreibe nicht nur `[[Link]]`, sondern `[[rel:depends_on Link]]`. Sag dem System *wie* Dinge zusammenhängen.
|
||||||
|
4. **Werte & Ziele definieren:** Damit die **Decision Engine** dich beraten kann, musst du deine Kriterien (`type: value`, `type: goal`) explizit als Notizen anlegen.
|
||||||
|
5. **Emotionales Bridging:** Damit die **Empathie** funktioniert, nutze in Erfahrungsberichten (`type: experience`) emotionale Schlüsselwörter ("Krise", "Freude", "Angst"), damit der Vektor-Retriever sie bei Gefühls-Anfragen findet.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Zweck & Scope
|
||||||
|
|
||||||
|
Dieses Handbuch ist die **primäre Arbeitsanweisung** für dich als Mindmaster (Owner) und alle Autoren, die Inhalte im mindnet-Vault erstellen.
|
||||||
|
|
||||||
|
### 1.1 Zielsetzung
|
||||||
|
Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit, Entscheidungen und Erfahrungen abbildet.
|
||||||
|
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).
|
||||||
|
|
||||||
|
### 1.2 Der Vault als „Source of Truth“
|
||||||
|
Die Markdown-Dateien in deinem Vault sind die **einzige Quelle der Wahrheit**.
|
||||||
|
* Mindnet importiert diesen Zustand deterministisch in die Datenbank (Qdrant).
|
||||||
|
* Änderungen an IDs, Typen oder Inhalten müssen **immer** im Markdown erfolgen, niemals direkt in der Datenbank.
|
||||||
|
* Was nicht im Markdown steht (z. B. implizites Wissen im Kopf), existiert für das System nicht.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Note-Struktur & Frontmatter
|
||||||
|
|
||||||
|
Jede Notiz benötigt einen YAML-Header (Frontmatter) am Dateianfang. Dieser Block macht die Notiz maschinenlesbar.
|
||||||
|
|
||||||
|
### 2.1 Pflichtfelder
|
||||||
|
Jede Datei muss mindestens folgende Felder enthalten, um korrekt verarbeitet zu werden:
|
||||||
|
|
||||||
|
---
|
||||||
|
id: 20251110-projekt-alpha-8a9b2c # Eindeutige Kennung (YYYYMMDD-slug)
|
||||||
|
title: Projekt Alpha # Sprechender Titel (wird in Suchergebnissen angezeigt)
|
||||||
|
type: project # Steuert Verarbeitung & Vernetzung (siehe Kap. 3)
|
||||||
|
status: active # Status (z.B. draft, active, archived)
|
||||||
|
created: 2025-11-10 # Erstellungsdatum (ISO 8601 oder YYYY-MM-DD)
|
||||||
|
updated: 2025-12-07 # Letzte Änderung
|
||||||
|
tags: [ki, entwicklung] # Taxonomie für Filterung
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2.2 Optionale Felder
|
||||||
|
Diese Felder sind technisch nicht zwingend, aber für bestimmte Typen sinnvoll:
|
||||||
|
|
||||||
|
lang: de # Sprache (Default: de)
|
||||||
|
aliases: [Alpha Projekt, Project A] # Synonyme für die Suche
|
||||||
|
visibility: internal # internal (default), public, private
|
||||||
|
|
||||||
|
> **Hinweis:** Felder wie `retriever_weight` oder `chunk_profile` sollten **nicht** mehr manuell im Frontmatter gesetzt werden. Diese werden zentral über den `type` gesteuert (siehe Kap. 3), um die Wartbarkeit zu sichern.
|
||||||
|
|
||||||
|
### 2.3 Empfehlungen für IDs und Pfade
|
||||||
|
|
||||||
|
**Die ID (Identifikator):**
|
||||||
|
* Muss global eindeutig und **stabil** sein.
|
||||||
|
* Darf sich nicht ändern, wenn die Datei umbenannt oder verschoben wird.
|
||||||
|
* **Empfehlung:** `YYYYMMDD-slug-hash` (z. B. `20231027-vektor-db-a1b2`). Dies garantiert Eindeutigkeit und Chronologie.
|
||||||
|
|
||||||
|
**Dateinamen & Pfade:**
|
||||||
|
* Pfade dienen der menschlichen Ordnung (Ordnerstruktur), sind für Mindnet aber sekundär.
|
||||||
|
* Dateinamen sollten dem Titel entsprechen (`Projekt Alpha.md`) oder dem Slug (`projekt-alpha.md`).
|
||||||
|
* Sonderzeichen vermeiden (außer Bindestrich und Unterstrich).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Note-Typen & Typ-Registry
|
||||||
|
|
||||||
|
Der `type` ist der wichtigste Hebel im Knowledge Design. Er steuert nicht nur das Gewicht bei der Suche, sondern seit WP-06 auch, **wann** eine Notiz aktiv in den Chat geholt wird ("Strategic Retrieval").
|
||||||
|
|
||||||
|
### 3.1 Übersicht der Kern-Typen
|
||||||
|
|
||||||
|
Mindnet unterscheidet verschiedene Wissensarten. Wähle den Typ, der die **Rolle** der Notiz am besten beschreibt:
|
||||||
|
|
||||||
|
| Typ | Beschreibung & Einsatzzweck | Rolle im Chat (Intent) |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **`concept`** | Fachbegriffe, Theorien. Zeitloses Wissen. | **FACT** (Basiswissen) |
|
||||||
|
| **`project`** | Ein Vorhaben mit Ziel, Dauer und Aufgaben. | **FACT / DECISION** (Kontext) |
|
||||||
|
| **`experience`** | Persönliche Erfahrung, Lektion oder Erkenntnis. | **EMPATHY** (Spiegelung) |
|
||||||
|
| **`decision`** | Eine bewusst getroffene Entscheidung (ADR). | **DECISION** (Begründung "Warum") |
|
||||||
|
| **`value`** | Ein persönlicher Wert oder ein Prinzip. | **DECISION** (Moralischer Kompass) |
|
||||||
|
| **`goal`** | Ein strategisches Ziel (kurz- oder langfristig). | **DECISION** (Abgleich) |
|
||||||
|
| **`person`** | Eine reale Person (Netzwerk, Autor). | **FACT** |
|
||||||
|
| **`journal`** | Zeitbezogener Log-Eintrag, Daily Note. | **FACT** (Historie) |
|
||||||
|
| **`source`** | Externe Quelle (Buch, PDF, Artikel). | **FACT** (Faktenbasis) |
|
||||||
|
|
||||||
|
### 3.2 Zusammenspiel mit `types.yaml`
|
||||||
|
|
||||||
|
Der `type` steuert im Hintergrund drei technische Mechanismen:
|
||||||
|
|
||||||
|
1. **`retriever_weight` (Wichtigkeit):**
|
||||||
|
* Ein `concept` (0.6) wiegt weniger als ein `project` (0.97) oder eine `decision` (1.0).
|
||||||
|
* **Warum?** Bei einer Suche nach "Datenbank" soll Mindnet bevorzugt deine *Entscheidung* ("Warum wir X nutzen") anzeigen.
|
||||||
|
2. **`chunk_profile` (Textzerlegung):**
|
||||||
|
* `journal` (short): Wird fein zerlegt.
|
||||||
|
* `project` (long): Längere Kontext-Fenster.
|
||||||
|
3. **`edge_defaults` (Automatische Vernetzung):**
|
||||||
|
* Mindnet ergänzt automatisch Kanten.
|
||||||
|
* Beispiel: Ein Link in einem `project` wird automatisch als `depends_on` (Abhängigkeit) interpretiert.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Edges & Referenzen in Notes
|
||||||
|
|
||||||
|
Um aus isolierten Dateien ein **Netzwerk** zu machen, nutzen wir Verlinkungen. In Version 2.2 sind diese Verlinkungen die Basis für den **Hybrid Retriever** (Suche über Nachbarn).
|
||||||
|
|
||||||
|
### 4.1 Wikilinks (Die Basis-Referenz)
|
||||||
|
Der klassische Obsidian-Link.
|
||||||
|
|
||||||
|
Wir nutzen [[Qdrant]] als Vektordatenbank.
|
||||||
|
|
||||||
|
* **Bedeutung:** "Diese Notiz erwähnt Qdrant."
|
||||||
|
* **Edge-Typ:** `references`
|
||||||
|
|
||||||
|
### 4.2 Inline-Relationen (Semantische Verknüpfung)
|
||||||
|
Dies ist die **mächtigste** Methode. Du sagst dem System explizit, **wie** Dinge zusammenhängen.
|
||||||
|
|
||||||
|
Daher [[rel:depends_on Qdrant]].
|
||||||
|
Dieses Konzept ist [[rel:similar_to Pinecone]].
|
||||||
|
|
||||||
|
* **Syntax:** `[[rel:RELATION ZIEL]]`.
|
||||||
|
* **Gültige Relationen:**
|
||||||
|
* `depends_on`: Hängt ab von / Benötigt. (Trigger für hohe Graph-Relevanz).
|
||||||
|
* `similar_to`: Ähnelt / Ist vergleichbar mit.
|
||||||
|
* `related_to`: Hat zu tun mit (allgemein).
|
||||||
|
* `caused_by`: Wurde verursacht durch.
|
||||||
|
* `solves`: Löst (Problem).
|
||||||
|
|
||||||
|
### 4.3 Callout-Edges (Kuratierte Listen)
|
||||||
|
Für Zusammenfassungen oder "Siehe auch"-Blöcke am Ende einer Notiz.
|
||||||
|
|
||||||
|
> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]]
|
||||||
|
|
||||||
|
* **Funktion:** Erzeugt `related_to`-Kanten zu allen genannten Zielen in dieser Zeile.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Schreiben für den KI-Zwilling (New in v2.3)
|
||||||
|
|
||||||
|
Damit der **RAG-Chat (WP05/06)** nicht nur dumm Fakten wiedergibt, sondern dich berät, musst du "Futter" für die Decision Engine und das Empathie-Modul liefern.
|
||||||
|
|
||||||
|
### 5.1 Futter für die Decision Engine (`DECISION`)
|
||||||
|
Das System soll abwägen: "Passt Tool X zu mir?". Dazu muss es wissen, was "Du" bist.
|
||||||
|
|
||||||
|
**Best Practice: Werte definieren**
|
||||||
|
Erstelle Notizen mit `type: value`.
|
||||||
|
|
||||||
|
---
|
||||||
|
type: value
|
||||||
|
title: Prinzip: Datensparsamkeit
|
||||||
|
---
|
||||||
|
# Prinzip: Datensparsamkeit
|
||||||
|
Wir speichern nur das Minimum an Daten. Cloud-Uploads persönlicher Daten sind verboten, es sei denn, sie sind E2E-verschlüsselt.
|
||||||
|
|
||||||
|
**Best Practice: Ziele definieren**
|
||||||
|
Erstelle Notizen mit `type: goal`.
|
||||||
|
|
||||||
|
---
|
||||||
|
type: goal
|
||||||
|
title: Ziel: Unabhängigkeit 2026
|
||||||
|
---
|
||||||
|
# Ziel: Unabhängigkeit 2026
|
||||||
|
Bis Ende 2026 wollen wir alle SaaS-Abos durch Self-Hosted Lösungen ersetzt haben.
|
||||||
|
|
||||||
|
*Effekt:* Wenn du fragst "Soll ich Notion nutzen?", lädt die Engine diese beiden Notizen und antwortet: *"Nein, Notion ist SaaS und nicht E2E-verschlüsselt. Das verletzt dein Prinzip der Datensparsamkeit und dein Ziel der Unabhängigkeit."*
|
||||||
|
|
||||||
|
### 5.2 Futter für den Empathie-Modus (`EMPATHY`)
|
||||||
|
Das System soll dich verstehen, wenn du sagst: "Alles ist grau." Dazu braucht es deine Resonanzerfahrungen.
|
||||||
|
|
||||||
|
**Best Practice: Erfahrungen & Bridging**
|
||||||
|
Erstelle Notizen mit `type: experience`. Nutze im Text **emotionale Brückenwörter**, damit der Retriever auch bei abstrakten Gefühlen ("grau") einen Treffer landet.
|
||||||
|
|
||||||
|
---
|
||||||
|
type: experience
|
||||||
|
title: Erfahrung: Der Durchbruch nach der Krise
|
||||||
|
tags: [krise, hoffnung, grau, angst]
|
||||||
|
---
|
||||||
|
# Erfahrung: Der Durchbruch nach der Krise
|
||||||
|
Es gibt Projektphasen, da wirkt alles **sinnlos** und **grau**.
|
||||||
|
Ich habe gelernt: Das ist oft das Zeichen kurz vor dem Durchbruch.
|
||||||
|
Mein Mantra in solchen Zeiten: "Einfach weitermachen, der Nebel lichtet sich."
|
||||||
|
|
||||||
|
*Effekt:* Wenn du im Chat jammerst ("Alles ist sinnlos"), findet das System diese Notiz und spiegelt dir deine eigene Erfahrung zurück.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Best Practices & Beispiele (Klassik)
|
||||||
|
|
||||||
|
### 6.1 Beispiel: Projekt-Notiz
|
||||||
|
Projekte profitieren von `depends_on`, um Abhängigkeiten zu klären.
|
||||||
|
|
||||||
|
---
|
||||||
|
id: 20251115-proj-mindnet
|
||||||
|
title: Mindnet Implementierung
|
||||||
|
type: project
|
||||||
|
status: active
|
||||||
|
---
|
||||||
|
|
||||||
|
# Mindnet Implementierung
|
||||||
|
|
||||||
|
Wir bauen ein persönliches Wissensnetz.
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
Wir nutzen [[rel:depends_on Qdrant]] für die Vektorsuche und [[rel:depends_on FastAPI]] für das Backend.
|
||||||
|
|
||||||
|
## Architektur
|
||||||
|
Das Konzept basiert auf [[RAG Architecture]]. (Automatisch 'depends_on' durch Typ-Default).
|
||||||
|
|
||||||
|
### 6.2 Beispiel: Entscheidung (Decision Record)
|
||||||
|
Entscheidungen sind hoch gewichtet (`retriever_weight: 1.0`).
|
||||||
|
|
||||||
|
---
|
||||||
|
id: 20251120-adr-vektordb
|
||||||
|
title: ADR: Wahl von Qdrant
|
||||||
|
type: decision
|
||||||
|
status: final
|
||||||
|
tags: [architektur, db]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Entscheidung: Qdrant
|
||||||
|
|
||||||
|
Wir haben uns für Qdrant entschieden.
|
||||||
|
|
||||||
|
## Alternativen
|
||||||
|
Wir haben auch [[rel:similar_to Pinecone]] und [[rel:similar_to Weaviate]] betrachtet.
|
||||||
|
|
||||||
|
## Begründung
|
||||||
|
Qdrant erlaubt lokalen Betrieb und [[rel:solves Payload Filtering Requirements]].
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Langfristige Stabilität & Virtual Schema Layer
|
||||||
|
|
||||||
|
Mindnet ist auf Langlebigkeit ausgelegt.
|
||||||
|
|
||||||
|
### 7.1 Das "Virtual Schema" Prinzip
|
||||||
|
Wir vermeiden es, Logik in den Markdown-Dateien hart zu kodieren.
|
||||||
|
* Statt in jeder Notiz zu schreiben `chunk_size: 500`, schreiben wir nur `type: essay`.
|
||||||
|
* Wie groß ein Chunk für ein Essay ist, definieren wir in der Konfiguration (`types.yaml`).
|
||||||
|
|
||||||
|
### 7.2 Was bedeutet das für dich?
|
||||||
|
* Du kannst dich auf den Inhalt konzentrieren.
|
||||||
|
* Wenn wir in Zukunft (WP08) basierend auf Feedback lernen, dass "Projekte" noch wichtiger sind, ändern wir **eine Zeile** in der Konfiguration, und das gesamte System passt sich beim nächsten Import an.
|
||||||
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,186 @@
|
|||||||
|
# Mindnet v2.2 – Entwickler-Workflow
|
||||||
|
**Datei:** `DEV_WORKFLOW.md`
|
||||||
|
**Stand:** 2025-12-09 (Aktualisiert: LLM Timeouts & Systemd)
|
||||||
|
|
||||||
|
Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Die Architektur
|
||||||
|
|
||||||
|
* **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**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Der Zyklus: Von der Idee zum Release
|
||||||
|
|
||||||
|
### Phase 1: Entwicklung (Windows / VS Code)
|
||||||
|
|
||||||
|
Hier erstellst du die neue Funktion in einer sicheren Umgebung.
|
||||||
|
|
||||||
|
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:**
|
||||||
|
* Klicke wieder unten links auf `main`.
|
||||||
|
* Wähle `+ Create new branch...`.
|
||||||
|
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp06-decision`).
|
||||||
|
* Drücke **Enter**.
|
||||||
|
|
||||||
|
3. **Sicherheits-Check:**
|
||||||
|
* Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!**
|
||||||
|
|
||||||
|
4. **Coden:**
|
||||||
|
* Nimm deine Änderungen vor (z.B. neue YAML-Configs).
|
||||||
|
|
||||||
|
5. **Sichern & Hochladen:**
|
||||||
|
* **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**.
|
||||||
|
* **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Testen (Beelink / `mindnet_dev`)
|
||||||
|
|
||||||
|
Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.
|
||||||
|
|
||||||
|
1. **Einloggen:**
|
||||||
|
`ssh user@<BEELINK-IP>`
|
||||||
|
|
||||||
|
2. **In die Werkstatt gehen:**
|
||||||
|
`cd /home/llmadmin/mindnet_dev`
|
||||||
|
|
||||||
|
3. **Code holen:**
|
||||||
|
```bash
|
||||||
|
git fetch
|
||||||
|
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
|
||||||
|
git checkout feature/wp06-decision
|
||||||
|
git pull
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Umgebung vorbereiten (bei Bedarf):**
|
||||||
|
```bash
|
||||||
|
source .venv/bin/activate
|
||||||
|
pip install -r requirements.txt # Nur nötig bei neuen Paketen
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Test-Server aktualisieren (WICHTIG):**
|
||||||
|
Der Code ist da, aber der Prozess im RAM ist noch alt. Wir müssen den Service neustarten.
|
||||||
|
|
||||||
|
**Option A: Standard (Als Service laufen lassen)**
|
||||||
|
Ideal, wenn du nur testen willst, ob es läuft.
|
||||||
|
```bash
|
||||||
|
sudo systemctl restart mindnet-dev
|
||||||
|
|
||||||
|
# Logs prüfen (um Fehler zu sehen):
|
||||||
|
journalctl -u mindnet-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!)
|
||||||
|
sudo systemctl stop mindnet-dev
|
||||||
|
|
||||||
|
# 2. Manuell starten
|
||||||
|
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
|
||||||
|
|
||||||
|
# ... Testen ...
|
||||||
|
|
||||||
|
# 3. Wenn fertig: Service wieder anschalten (Optional)
|
||||||
|
# Strg+C drücken
|
||||||
|
sudo systemctl start mindnet-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...?"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Release (Gitea / Raspberry Pi)
|
||||||
|
|
||||||
|
Wenn der Test auf Port 8002 erfolgreich war:
|
||||||
|
|
||||||
|
1. Öffne Gitea im Browser.
|
||||||
|
2. Erstelle einen **Pull Request** (Dein Branch -> `main`).
|
||||||
|
3. **Merge** den Pull Request.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 4: Deployment (Beelink / `mindnet`)
|
||||||
|
|
||||||
|
Jetzt bringen wir die Änderung in das Live-System (Port 8001).
|
||||||
|
|
||||||
|
1. **Deploy-Agent (Automatisch):**
|
||||||
|
Wenn dein `deploy.yml` aktiv ist, passiert das jetzt von selbst!
|
||||||
|
|
||||||
|
2. **Manuell (Falls nötig):**
|
||||||
|
```bash
|
||||||
|
cd /home/llmadmin/mindnet
|
||||||
|
git pull origin main
|
||||||
|
|
||||||
|
# Produktions-Service neustarten
|
||||||
|
sudo systemctl restart mindnet-prod
|
||||||
|
|
||||||
|
# Kurz prüfen, ob er läuft
|
||||||
|
sudo systemctl status mindnet-prod
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 5: Aufräumen (Optional aber empfohlen)
|
||||||
|
|
||||||
|
Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
|
||||||
|
|
||||||
|
1. **Gitea:** Im Pull Request auf "Delete Branch" klicken.
|
||||||
|
2. **Beelink (Dev):**
|
||||||
|
```bash
|
||||||
|
cd ~/mindnet_dev
|
||||||
|
git checkout main
|
||||||
|
git pull
|
||||||
|
git branch -d feature/wp06-decision
|
||||||
|
```
|
||||||
|
3. **VS Code:**
|
||||||
|
* Auf `main` wechseln.
|
||||||
|
* Sync drücken.
|
||||||
|
* `F1` -> `Git: Delete Branch` -> Branch auswählen.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Cheat Sheet: Die wichtigsten Befehle
|
||||||
|
|
||||||
|
| Wo? | Befehl | Was tut es? |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **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.** |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Troubleshooting
|
||||||
|
|
||||||
|
**"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`).
|
||||||
|
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`.
|
||||||
|
|
||||||
|
**"UnicodeDecodeError in .env"**
|
||||||
|
* **Ursache:** Umlaute oder Sonderzeichen in der `.env` Datei.
|
||||||
|
* **Lösung:** `.env` bereinigen (nur ASCII nutzen) und sicherstellen, dass sie UTF-8 ohne BOM ist.
|
||||||
@@ -0,0 +1,265 @@
|
|||||||
|
# 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)
|
||||||
|
**Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`.
|
||||||
|
|
||||||
|
> **Zielgruppe:** Entwickler:innen.
|
||||||
|
> **Zweck:** Anleitung zum Aufsetzen der Entwicklungsumgebung, Verständnis der Modulstruktur und Durchführung von Tests.
|
||||||
|
|
||||||
|
---
|
||||||
|
- [Mindnet v2.2 – Developer Guide](#mindnet-v22--developer-guide)
|
||||||
|
- [1. Projektstruktur (Post-WP06)](#1-projektstruktur-post-wp06)
|
||||||
|
- [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)
|
||||||
|
- [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)
|
||||||
|
- [4. Tests \& Debugging](#4-tests--debugging)
|
||||||
|
- [4.1 Unit Tests (Pytest)](#41-unit-tests-pytest)
|
||||||
|
- [4.2 Integration / Pipeline Tests](#42-integration--pipeline-tests)
|
||||||
|
- [4.3 Smoke Tests (E2E)](#43-smoke-tests-e2e)
|
||||||
|
- [5. Das "Teach-the-AI" Paradigma (Context Intelligence)](#5-das-teach-the-ai-paradigma-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 (Edges) nutzen (z. B. `beeinflusst_von`)](#b-workflow-neue-beziehungen-edges-nutzen-z-b-beeinflusst_von)
|
||||||
|
- [Fazit](#fazit)
|
||||||
|
- [6. Nützliche Einzeiler](#6-nützliche-einzeiler)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Projektstruktur (Post-WP06)
|
||||||
|
|
||||||
|
Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt.
|
||||||
|
|
||||||
|
mindnet/
|
||||||
|
├── app/
|
||||||
|
│ ├── core/ # Kernlogik
|
||||||
|
│ │ ├── chunker.py # Text-Zerlegung
|
||||||
|
│ │ ├── derive_edges.py # Edge-Erzeugung (WP03 Logik)
|
||||||
|
│ │ ├── retriever.py # Scoring & Hybrid Search
|
||||||
|
│ │ ├── qdrant.py # DB-Verbindung
|
||||||
|
│ │ └── ...
|
||||||
|
│ ├── models/ # Pydantic DTOs
|
||||||
|
│ │ └── dto.py # Zentrale DTO-Definition
|
||||||
|
│ ├── routers/ # FastAPI Endpoints
|
||||||
|
│ │ ├── query.py # Suche
|
||||||
|
│ │ ├── chat.py # Hybrid Router & Decision Engine (WP06)
|
||||||
|
│ │ ├── feedback.py # Feedback (WP04c)
|
||||||
|
│ │ └── ...
|
||||||
|
│ ├── services/ # Interne & Externe Dienste
|
||||||
|
│ │ ├── llm_service.py # Ollama Client (Mit Timeout & Raw-Mode)
|
||||||
|
│ │ ├── feedback_service.py # Logging (JSONL Writer)
|
||||||
|
│ │ └── embeddings_client.py
|
||||||
|
│ └── main.py # Entrypoint der API
|
||||||
|
├── config/ # YAML-Konfigurationen (Single Source of Truth)
|
||||||
|
│ ├── types.yaml # Import-Regeln
|
||||||
|
│ ├── prompts.yaml # LLM Prompts & RAG Templates (WP06)
|
||||||
|
│ ├── decision_engine.yaml # Router-Strategien (WP06)
|
||||||
|
│ └── retriever.yaml # Scoring-Regeln & Kantengewichte
|
||||||
|
├── data/
|
||||||
|
│ └── logs/ # Lokale Logs (search_history.jsonl, feedback.jsonl)
|
||||||
|
├── scripts/ # CLI-Tools (Import, Diagnose, Reset)
|
||||||
|
├── tests/ # Pytest Suite & Smoke Scripts
|
||||||
|
└── vault/ # Dein lokaler Markdown-Content (Git-ignored)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Lokales Setup (Development)
|
||||||
|
|
||||||
|
### 2.1 Voraussetzungen
|
||||||
|
* **Python:** 3.10 oder höher.
|
||||||
|
* **Docker:** Für Qdrant.
|
||||||
|
* **Ollama:** Für lokale LLM-Inference (erforderlich für `/chat`).
|
||||||
|
* **Vault:** Ein Ordner mit Markdown-Dateien (z.B. `./mindnet_v2_test_vault` für Tests).
|
||||||
|
|
||||||
|
### 2.2 Installation
|
||||||
|
|
||||||
|
# 1. Repository klonen & Verzeichnis wechseln
|
||||||
|
git clone <repo> mindnet
|
||||||
|
cd mindnet
|
||||||
|
|
||||||
|
# 2. Virtual Environment erstellen
|
||||||
|
python3 -m venv .venv
|
||||||
|
source .venv/bin/activate
|
||||||
|
|
||||||
|
# 3. Abhängigkeiten installieren
|
||||||
|
pip install -r requirements.txt
|
||||||
|
|
||||||
|
# 4. Ollama Setup (Modell laden)
|
||||||
|
# Wir nutzen Phi-3 Mini für schnelle CPU-Inference
|
||||||
|
ollama pull phi3:mini
|
||||||
|
|
||||||
|
### 2.3 Konfiguration (Environment)
|
||||||
|
Erstelle eine `.env` Datei im Root-Verzeichnis. Die Timeout-Settings sind kritisch für CPU-Inference.
|
||||||
|
|
||||||
|
# Qdrant Verbindung
|
||||||
|
QDRANT_URL="http://localhost:6333"
|
||||||
|
QDRANT_API_KEY="" # Leer lassen für lokal
|
||||||
|
|
||||||
|
# Mindnet Core Settings
|
||||||
|
COLLECTION_PREFIX="mindnet_dev"
|
||||||
|
MINDNET_TYPES_FILE="./config/types.yaml"
|
||||||
|
MINDNET_RETRIEVER_CONFIG="./config/retriever.yaml"
|
||||||
|
|
||||||
|
# LLM / RAG Settings (WP06)
|
||||||
|
MINDNET_LLM_MODEL="phi3:mini"
|
||||||
|
MINDNET_OLLAMA_URL="http://127.0.0.1:11434"
|
||||||
|
MINDNET_LLM_TIMEOUT=300.0
|
||||||
|
MINDNET_PROMPTS_PATH="./config/prompts.yaml"
|
||||||
|
MINDNET_DECISION_CONFIG="./config/decision_engine.yaml"
|
||||||
|
|
||||||
|
# Import-Strategie
|
||||||
|
MINDNET_HASH_COMPARE="Body"
|
||||||
|
MINDNET_HASH_SOURCE="parsed"
|
||||||
|
|
||||||
|
### 2.4 Dienste starten (Systemd bevorzugt)
|
||||||
|
Auf dem Entwicklungsserver (Beelink) nutzen wir Systemd.
|
||||||
|
|
||||||
|
# Starten / Neustarten
|
||||||
|
sudo systemctl restart mindnet-dev
|
||||||
|
|
||||||
|
# Logs prüfen (Wichtig für LLM Debugging)
|
||||||
|
journalctl -u mindnet-dev -f
|
||||||
|
|
||||||
|
Falls du lokal auf Windows entwickelst:
|
||||||
|
|
||||||
|
# 1. Qdrant starten
|
||||||
|
docker run -p 6333:6333 qdrant/qdrant
|
||||||
|
# 2. Ollama starten
|
||||||
|
ollama serve
|
||||||
|
# 3. API starten
|
||||||
|
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env --reload
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Core-Module & Entwicklung
|
||||||
|
|
||||||
|
### 3.1 Der Importer (`scripts.import_markdown`)
|
||||||
|
Dies ist das komplexeste Modul.
|
||||||
|
* **Einstieg:** `scripts/import_markdown.py` -> `main()`.
|
||||||
|
* **Idempotenz:** Der Importer muss mehrfach laufen können, ohne Duplikate zu erzeugen. Wir nutzen deterministische IDs (UUIDv5).
|
||||||
|
* **Debugging:** Nutze `--dry-run` oder `scripts/payload_dryrun.py`.
|
||||||
|
|
||||||
|
### 3.2 Der Hybrid Router (`app.routers.chat`)
|
||||||
|
Hier liegt die Logik für Intent Detection (WP06).
|
||||||
|
* **Logic:** `_classify_intent` prüft zuerst Keywords (Fast Path) und fällt auf `llm_service.generate_raw_response` zurück (Slow Path), wenn konfiguriert.
|
||||||
|
* **Config:** Gesteuert durch `decision_engine.yaml`.
|
||||||
|
* **Erweiterung:** Um neue Intents hinzuzufügen, editiere nur die YAML, nicht den Python-Code (Late Binding).
|
||||||
|
|
||||||
|
### 3.3 Der Retriever (`app.core.retriever`)
|
||||||
|
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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Tests & Debugging
|
||||||
|
|
||||||
|
Wir unterscheiden drei Test-Ebenen. Ein Pull Request sollte alle passieren.
|
||||||
|
|
||||||
|
### 4.1 Unit Tests (Pytest)
|
||||||
|
Für isolierte Logik (Parsing, Scoring).
|
||||||
|
|
||||||
|
pytest tests/test_retriever_basic.py
|
||||||
|
pytest tests/test_chunking.py
|
||||||
|
pytest tests/test_edges_all.py
|
||||||
|
|
||||||
|
### 4.2 Integration / Pipeline Tests
|
||||||
|
Prüfen den Datenfluss von Markdown bis Qdrant-JSON.
|
||||||
|
* **Payload Dryrun:** Prüft JSON-Schema Konformität.
|
||||||
|
|
||||||
|
python3 -m scripts.payload_dryrun --vault ./mindnet_v2_test_vault
|
||||||
|
|
||||||
|
* **Edge Checks:** Prüft Graph-Invarianten.
|
||||||
|
|
||||||
|
python3 -m scripts.edges_full_check
|
||||||
|
|
||||||
|
### 4.3 Smoke Tests (E2E)
|
||||||
|
Prüfen das laufende System (API) 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)
|
||||||
|
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"
|
||||||
|
|
||||||
|
# 4. Feedback Test (WP04c)
|
||||||
|
python tests/test_feedback_smoke.py --url http://localhost:8002/query
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Das "Teach-the-AI" Paradigma (Context Intelligence)
|
||||||
|
|
||||||
|
Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration**, **Vernetzung** und **Prompting**. Wenn du dem System ein neues Konzept beibringen willst, musst du in der Regel an drei Stellen eingreifen. Dies ist der **Core-Workflow** für Erweiterungen.
|
||||||
|
|
||||||
|
### A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)
|
||||||
|
|
||||||
|
**1. Daten-Ebene (`config/types.yaml`)**
|
||||||
|
Definiere die "Physik" des Typs (Import-Regeln und Basis-Wichtigkeit).
|
||||||
|
|
||||||
|
risk:
|
||||||
|
chunk_profile: short # Risiken sind oft kurze Statements
|
||||||
|
retriever_weight: 0.90 # Sehr wichtig, fast so hoch wie Decisions
|
||||||
|
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
|
||||||
|
|
||||||
|
**2. Strategie-Ebene (`config/decision_engine.yaml`)**
|
||||||
|
Damit dieser Typ aktiv geladen wird, musst du ihn einer Strategie zuordnen.
|
||||||
|
|
||||||
|
DECISION:
|
||||||
|
inject_types: ["value", "principle", "goal", "risk"] # <--- "risk" hinzugefügt
|
||||||
|
|
||||||
|
*Ergebnis:* Wenn der Intent `DECISION` erkannt wird, sucht das System nun auch aktiv nach Risiken.
|
||||||
|
|
||||||
|
**3. Kognitive Ebene (`config/prompts.yaml`)**
|
||||||
|
Erkläre dem LLM im Template, was es damit tun soll.
|
||||||
|
|
||||||
|
decision_template: |
|
||||||
|
...
|
||||||
|
- Prüfe auf [RISK]: Wenn vorhanden, warne mich davor!
|
||||||
|
|
||||||
|
### B. Workflow: Neue Beziehungen (Edges) nutzen (z. B. `beeinflusst_von`)
|
||||||
|
|
||||||
|
Beziehungen sind der Klebstoff für die "Why"-Erklärungen.
|
||||||
|
|
||||||
|
**1. Erfassung im Vault (Markdown)**
|
||||||
|
Du musst dem System keinen neuen Edge-Typ "beibringen" (Schema-less). Du nutzt ihn einfach.
|
||||||
|
Nutze die Inline-Syntax im Fließtext:
|
||||||
|
|
||||||
|
Die Entscheidung für Qdrant wurde [[rel:beeinflusst_von Budgetkürzung 2024]].
|
||||||
|
|
||||||
|
**2. Gewichtung (`config/retriever.yaml`)**
|
||||||
|
Standardmäßig werden alle expliziten Kanten gleich behandelt. Wenn Kausalität wichtiger ist als Ähnlichkeit, konfiguriere dies hier.
|
||||||
|
|
||||||
|
scoring:
|
||||||
|
edge_type_weights:
|
||||||
|
beeinflusst_von: 1.5 # Sehr starker Einfluss auf das Ranking
|
||||||
|
|
||||||
|
### Fazit
|
||||||
|
* **Vault:** Liefert das Wissen.
|
||||||
|
* **Config:** Liefert die Strategie (Router & Weights).
|
||||||
|
* **Prompt:** Liefert die Interpretation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Nützliche Einzeiler
|
||||||
|
|
||||||
|
**DB komplett zurücksetzen (Vorsicht!):**
|
||||||
|
|
||||||
|
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes
|
||||||
|
|
||||||
|
**Einen einzelnen File inspizieren (Parser-Sicht):**
|
||||||
|
|
||||||
|
python3 tests/inspect_one_note.py --file ./vault/MeinFile.md
|
||||||
|
|
||||||
|
**Live-Logs sehen (Beelink) - inkl. LLM Thoughts:**
|
||||||
|
|
||||||
|
journalctl -u mindnet-dev -f
|
||||||
@@ -1,216 +0,0 @@
|
|||||||
# mindnet – Knowledge Design
|
|
||||||
**Version:** 1.5.0 (aktualisiert 2025-11-09)
|
|
||||||
|
|
||||||
> Dieses Dokument beschreibt das Ziel, die Architektur, die Datenmodelle sowie die Regeln und Prozesse für den Aufbau von **mindnet** – einem persönlichen, lokal betriebenen Wissensnetz, das auf Markdown-Quellen, Graph-Beziehungen und Vektor-Suche basiert. Es soll die Persönlichkeit, Werte und Erfahrungen des Besitzers widerspiegeln und künftig Antworten generieren, die diese Perspektive authentisch berücksichtigen.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. Ziel von mindnet
|
|
||||||
|
|
||||||
**1.1 Zweck**
|
|
||||||
- mindnet dient als persönliches Wissensnetz, das Erfahrungen, Werte, Prinzipien, Ziele und prägenden Ereignisse langfristig strukturiert.
|
|
||||||
- Es ermöglicht spätere Einsichten in Entscheidungen und Entwicklungen und kann in Zukunft für die Familie (z. B. Kinder) eine nachvollziehbare Quelle sein.
|
|
||||||
|
|
||||||
**1.2 Leitidee**
|
|
||||||
- Statt einer reinen Dokumentablage wird Wissen durch **Knoten (Notes/Chunks)** und **Kanten (Edges)** vernetzt.
|
|
||||||
- Antworten sollen **persönlich** kontextualisiert werden (Perspektive, Konditionierung, Persönlichkeit).
|
|
||||||
|
|
||||||
**1.3 Langfristigkeit**
|
|
||||||
- Stabiler, zukunftsfähiger Entwurf; spätere Massenmigrationen sollen vermieden werden.
|
|
||||||
- Architektur unterstützt schrittweise Erweiterung (neue Quellen, neue Agenten, neue Regeln).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. Zielarchitektur (High Level)
|
|
||||||
|
|
||||||
- **Datenquellen:** Markdown-Vault (Obsidian-kompatibel), perspektivisch weitere Quellen (MediaWiki, PDFs, Web-Exporte, E-Mail-Auszüge).
|
|
||||||
- **Import-Pipeline:** Parser → Frontmatter/Body → Chunking → Embedding → Qdrant (Notes/Chunks/Edges).
|
|
||||||
- **Speicher:** Qdrant (Vektoren + Payload + Textindex), Dateien bleiben im Filesystem (Quelle ist Referenz).
|
|
||||||
- **Graph-Schicht:** Edges explizit modelliert (Typ, Richtung, Evidenz, Confidence); optionale abgeleitete Edges per Batch-Job.
|
|
||||||
- **Retriever/Composer:** Hybrid-Retrieval (Vektor + Filter + optional Volltext), Komposition zu Antwortkandidaten.
|
|
||||||
- **Erklärbarkeit:** Begründungspfade (Top-Chunks, Graph-Kette, Provenienz).
|
|
||||||
- **Schnittstellen:** REST/CLI, n8n-Glue, lokale LLM-Anbindung (Ollama).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Collections in Qdrant
|
|
||||||
|
|
||||||
- `mindnet_notes` – Note-Metadaten (id, title, type, path, timestamps, tags, …).
|
|
||||||
- `mindnet_chunks` – inhaltstragende Segmente inkl. Vektoren und Textindex.
|
|
||||||
- `mindnet_edges` – Beziehungen (src/dst, relation, direction, evidence, confidence, …).
|
|
||||||
- (optional) `mindnet_people` – strukturierte Personenobjekte (Eigen-/Fremdbezug).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. Identitäten & IDs
|
|
||||||
|
|
||||||
- **Deterministische IDs** für Notes (z. B. Namespace-basierte UUIDv5) und stabile, ableitbare IDs für Chunks/Edges.
|
|
||||||
- ID-Stabilität ist Voraussetzung für Idempotenz (Re-Imports ohne Duplikate).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. Frontmatter & Typen
|
|
||||||
|
|
||||||
- Pflichtfelder: `id`, `title`, `type`, `created`, `updated`, `tags`, `source_path`.
|
|
||||||
- Note-Typen (Auszug): `experience`, `principle`, `value`, `goal`, `role`, `persona`, `plan`, `project`, `journal`, `reference`, `translation`.
|
|
||||||
- **types.yaml** definiert Regeln/Defaults je Typ und für Relationstypen (siehe Abschnitt 10).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Chunking-Strategie
|
|
||||||
|
|
||||||
- Satz- bis Absatz-Chunks, moderate Überlappung; Meta-Felder verweisen auf Note/Quelle.
|
|
||||||
- Named Vectors (z. B. `content`, optional `title`, `tags`) ermöglichen hybride Scores.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Embeddings & Vektoren
|
|
||||||
|
|
||||||
- Einheitliche Metrik (cosine), reproduzierbares Embedding-Setup.
|
|
||||||
- Konsistenz über Zeit durch Versionsfeld (`embedding_model`, `embedding_version`).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. Volltext & Filter
|
|
||||||
|
|
||||||
- Textindex auf `mindnet_chunks.body` für exakte Term/Operator-Queries.
|
|
||||||
- Payload-Filter zur schnellen Einschränkung (tags, types, time-buckets, visibility u. a.).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. Edges – Beziehungen
|
|
||||||
|
|
||||||
- **Explizit**: Jede tatsächliche Beziehung wird als Kante gespeichert (kein Workaround).
|
|
||||||
- Felder u. a.: `src_id`, `dst_id`, `relation`, `direction`, `confidence (0–1)`, `evidence` (Chunk-IDs), `created_at`, `updated_at`.
|
|
||||||
- **edge_defaults** liefern **Interpretations-Hints** (Gewichte, Symmetrie, Transitivität) und parametrisieren abgeleitete Edges; sie **ersetzen** keine Originalkanten.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. Regeln & Policies (types.yaml)
|
|
||||||
|
|
||||||
- Per Typ/Relation:
|
|
||||||
- Default-Eigenschaften (Gewicht, Directedness, Symmetrie, Transitivität).
|
|
||||||
- Scoring-Hooks für Graph-Kontext im Retriever.
|
|
||||||
- (später) Privacy-Hooks je Relation (Mindest-Visibility).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 11. Retrieval & Ranking (Komposition)
|
|
||||||
|
|
||||||
- Hybrid: Vektor-Score + Filter + optional BM25/Volltext.
|
|
||||||
- Zeitgewicht (Decays) und Graph-Kontext werden komponiert (Formel siehe 16.3).
|
|
||||||
- Konfiguration über `.env`/`config.yaml` (gewichts- und halbwertszeit-basiert).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 12. Erklärbarkeit
|
|
||||||
|
|
||||||
- „Warum-Pfad“: Top-Chunks mit Score-Zerlegung (Vektor/Time/Graph), Graph-Kette, Provenienz.
|
|
||||||
- Mehrschichtige Narrative (Kindheit/Erlebnisse, Werte/Prinzipien, Ziele/Leitbild, Gegenwart).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 13. Betrieb & Sicherheit
|
|
||||||
|
|
||||||
- Lokal auf Single-Node starten (Backups via Snapshots).
|
|
||||||
- Zugriff nur intern/Reverse-Proxy; Festplattenverschlüsselung OS-seitig.
|
|
||||||
- Migrationspfad zu Qdrant-Distributed (Shards, Replikation) einplanen.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 14. Qualität & Monitoring
|
|
||||||
|
|
||||||
- Offline-Eval-Sets, Telemetrie (lokal), Drift-Checks, manuelle Reviews.
|
|
||||||
- Kennzahlen: Hit-Rate, Overlap, Quellen-Alter, Erklärungspfad-Nutzung.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 15. Offene Punkte
|
|
||||||
|
|
||||||
- Ausdetaillierung `types.yaml` (Relationen, Hooks).
|
|
||||||
- UI-Oberfläche für Erklärpfade und Provenienz.
|
|
||||||
- Batch-Jobs für abgeleitete Edges.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 16. Ergänzungen 2025-11-09 (v1.5.0)
|
|
||||||
|
|
||||||
**Kontext:** Basierend auf den neuen Rahmenbedingungen (nur Deutsch; perspektivische externe Abfragen; einheitliche Vertraulichkeit mit Option auf feinere Stufen; Recency-Priorisierung als Default; Regeln später konfigurierbar; zunächst lokale Speicherung mit optionaler Migration; heutige Hardware, später skalierbar; hohe Erklärbarkeit mit mehreren Erklärungsebenen) werden folgende Entscheidungen und Erweiterungen getroffen. Alle bisherigen Inhalte bleiben gültig und werden **nicht** verändert.
|
|
||||||
|
|
||||||
### 16.1 Sprach- und Inhaltsrichtlinie (nur Deutsch)
|
|
||||||
- `lang: "de"` als verpflichtendes Feld in allen Note-, Chunk- und Edge-Payloads.
|
|
||||||
- Für spätere Mehrsprachigkeit **nicht** die Collection splitten, sondern ein Feld `lang` + optional `lang_original` behalten; Translation-Artefakte als eigener `type: translation` (verweisend auf `source_id`).
|
|
||||||
|
|
||||||
### 16.2 Vertraulichkeit & Sichtbarkeit
|
|
||||||
- Heute: einheitliche Stufe `visibility: "internal"`.
|
|
||||||
- Vorausschauend: reservierte Felder in allen Payloads
|
|
||||||
- `visibility`: `"public" | "internal" | "restricted"`
|
|
||||||
- `sensitivity`: Integer 0–3 (0 = unkritisch, 3 = hochsensibel)
|
|
||||||
- `acl`: Liste erlaubter Rollen/Personen-IDs (App-Layer erzwingt Filter vor Query).
|
|
||||||
- Access-Control erfolgt **im Applikations-Layer** mittels Qdrant-Payload-Filtern (`must: [ { key: "visibility", match: { any: [...] }}, ... ]`); Qdrant bleibt „dumm“ in Bezug auf ACL.
|
|
||||||
|
|
||||||
### 16.3 Recency-Modell & Ranking (konfigurierbar)
|
|
||||||
- Default: **Zeitnähe** priorisieren (sanfte Abwertung älterer Inhalte).
|
|
||||||
- Im Retrieval kombinieren wir:
|
|
||||||
1) Vektor-Score (cosine) aus Qdrant
|
|
||||||
2) Zeitgewicht `time_decay = exp( - ln(2) * age_days / half_life_days )`
|
|
||||||
3) Graph-Kontext aus Edges (z. B. Degree, Path-Hops zum Anker „Ich/Persona“)
|
|
||||||
- Konfigurierbare Gewichte (per `.env` oder `config.yaml`):
|
|
||||||
```text
|
|
||||||
FINAL_SCORE = w_vec * norm(vec_score)
|
|
||||||
+ w_time * time_decay
|
|
||||||
+ w_graph * graph_context_score
|
|
||||||
# Vorschlag: w_vec=0.70, w_time=0.20, w_graph=0.10; half_life_days=365
|
|
||||||
```
|
|
||||||
- Für Fragen, die „zeitlos“ sind, kann `half_life_days = inf` gesetzt werden (kein Decay).
|
|
||||||
|
|
||||||
### 16.4 Erklärbarkeit („Warum diese Antwort?“)
|
|
||||||
- Jeder Antwort wird ein **Erklärpfad** mitgegeben (optional im UI):
|
|
||||||
- Top-Chunks (mit Score-Zerlegung w_vec/w_time/w_graph)
|
|
||||||
- **Kausalpfad** im Graphen: `Note → Edge(relation, confidence) → Note …`
|
|
||||||
- **Provenienz** (Quelle, Erstellungszeit, letzte Änderung).
|
|
||||||
- Ein **Multi-Layer-Explanations**-Modul ordnet Beiträge zu: Kindheit/Erlebnisse, Werte & Prinzipien, aktuelle Ziele/Leitbild, Gegenwartskontext.
|
|
||||||
|
|
||||||
### 16.5 Qdrant-Schemata (Ergänzungen, rückwärtskompatibel)
|
|
||||||
- **Collections** bleiben: `mindnet_notes`, `mindnet_chunks`, `mindnet_edges` (+ `mindnet_people` falls noch nicht vorhanden).
|
|
||||||
- Gemeinsame Zusatzfelder (alle Payloads):
|
|
||||||
- `lang: "de"`
|
|
||||||
- `visibility`/`sensitivity`/`acl` (s. 16.2)
|
|
||||||
- `created_at` (ISO-8601), `updated_at` (ISO-8601), `age_days` (App-seitig berechnet)
|
|
||||||
- **Chunks**:
|
|
||||||
- Named-Vectors (z. B. `"content"`, optional `"title"`, `"tags"` für Hybrid-Scores).
|
|
||||||
- `text_index` auf `body` für BM25-ähnliche Volltextsuche (Qdrant-Textindex).
|
|
||||||
- `recency_group`: Jahr-Monat `YYYY-MM` (ermöglicht Pre-Filter für „letzte N Monate“).
|
|
||||||
- **Edges** (explizit, keine Workarounds):
|
|
||||||
- Felder: `src_id`, `dst_id`, `relation`, `direction`, `confidence` (0–1), `evidence` (Chunk-IDs), `created_at`, `updated_at`.
|
|
||||||
- **edge_defaults** bleiben als **Interpretations-Hints**: z. B. `default_weight`, `symmetry`, `transitivity`. Sie ersetzen **nicht** echte Kanten, sondern parametrisieren abgeleitete/zusätzliche Kantenbildung.
|
|
||||||
- Abgeleitete Edges: optionaler Batch-Job erzeugt *ergänzende* Kanten entlang `types.yaml`-Regeln (z. B. Backlinks, „inspired_by“ aus Zitaten), niemals statt der Originalkanten.
|
|
||||||
|
|
||||||
### 16.6 Regeln & Typen (konfigurierbar)
|
|
||||||
- `types.yaml` erweitert um:
|
|
||||||
- Relationstypen mit Default-Eigenschaften (`weight`, `directed`, `symmetric`, `transitive`).
|
|
||||||
- **Scoring-Hooks**: pro Relation optionaler Einfluss auf `graph_context_score`.
|
|
||||||
- **Privacy-Hooks**: pro Relation Minimal-Visibility (z. B. Beziehungen zu Personen sind mindestens `internal`).
|
|
||||||
|
|
||||||
### 16.7 Speicher- & Betriebsstrategie (heute lokal, später skalierbar)
|
|
||||||
- **Heute**: Single-Node Qdrant mit HNSW-Index, Text-Index und Payload-Filtern; regelmäßiges Backup (Snapshots).
|
|
||||||
- **Morgen**: Migrationspfad in **Qdrant-Distributed** (Shards, ggf. Replikation) bei Bedarf; Parameter-Gleichheit sichern (named-vectors, Metrik, HNSW-Param).
|
|
||||||
- **Sicherheit**: Zugriff nur über internes Netz/Reverse-Proxy, Auth vor Qdrant; Festplatten-Verschlüsselung auf OS-Ebene (z. B. LUKS).
|
|
||||||
|
|
||||||
### 16.8 Persona-Layer („meine Essenz“)
|
|
||||||
- Eigenständiger **Persona-Knoten** (z. B. Note `person/lars`), verbunden mit:
|
|
||||||
- Werten/Prinzipien, Leitbild, prägenden Erlebnissen, Zielen, Rollen.
|
|
||||||
- Jede Antwort kann gegen diesen Knoten **kontextualisiert** werden (Graph-Pfadnähe).
|
|
||||||
- Feld `persona_weight` in Chunks/Notes zur Priorisierung persönlicher Relevanz.
|
|
||||||
|
|
||||||
### 16.9 Evaluierung & Qualitätssicherung
|
|
||||||
- **Offline-Sets** aus echten Fragen (inkl. gewünschter Perspektiven) mit erwarteten Top-Quellen.
|
|
||||||
- **Telemetrie** (lokal): Query-Arten, Treffer-Overlaps, Zeitgewicht-Effekte, „Warum-Pfad“ genutzt/ignoriert.
|
|
||||||
- **Drift-Checks**: Anteil sehr alter vs. neuer Quellen in Antworten; manuelle Reviews.
|
|
||||||
|
|
||||||
### 16.10 Offene Punkte / Nächste Schritte
|
|
||||||
1) `types.yaml` um Relationseigenschaften erweitern (s. 16.6).
|
|
||||||
2) Retriever-Komposition inkl. Zeitgewicht (s. 16.3) implementieren.
|
|
||||||
3) Explanations-Pfad inkl. Provenienzoberfläche (s. 16.4) im UI.
|
|
||||||
4) Feld-Erweiterungen in Import-Pipelines (`lang`, `visibility`, Zeitfelder).
|
|
||||||
5) Optional: Batch-Job für abgeleitete Edges nach Regeln (ergänzend, nicht ersetzend).
|
|
||||||
@@ -1,19 +1,66 @@
|
|||||||
# Mindnet – Fachliche Architektur (Stand: 2025-11-17)
|
# Mindnet v2.2 – Fachliche Architektur
|
||||||
|
**Datei:** `docs/mindnet_functional_architecture_v2.2.md`
|
||||||
|
**Stand:** 2025-12-09
|
||||||
|
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
|
||||||
|
|
||||||
> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten) zwischen Notizen/Chunks. Die technische Umsetzung (Module, Flags, Schemas) wird nur dort angerissen, wo es zum Verständnis nötig ist und 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 neuen **RAG-Chat** (Decision Engine & Persönlichkeit). Die technische Umsetzung wird im technischen Dokument detailliert.
|
||||||
|
|
||||||
|
---
|
||||||
|
<details>
|
||||||
|
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
|
||||||
|
|
||||||
|
- [Mindnet v2.2 – Fachliche Architektur](#mindnet-v22--fachliche-architektur)
|
||||||
|
- [](#)
|
||||||
|
- [0) Zielbild \& Grundprinzip](#0-zielbild--grundprinzip)
|
||||||
|
- [1) Notizen \& Chunks (fachliche Perspektive)](#1-notizen--chunks-fachliche-perspektive)
|
||||||
|
- [1.1 Notiz (Note)](#11-notiz-note)
|
||||||
|
- [1.2 Chunk](#12-chunk)
|
||||||
|
- [2) Edges – fachliche Typen \& Bedeutung](#2-edges--fachliche-typen--bedeutung)
|
||||||
|
- [2.1 Struktur-Kanten (Das Skelett)](#21-struktur-kanten-das-skelett)
|
||||||
|
- [2.2 Inhalts-Kanten (explizit)](#22-inhalts-kanten-explizit)
|
||||||
|
- [2.3 Typ-basierte Default-Kanten (Regelbasiert)](#23-typ-basierte-default-kanten-regelbasiert)
|
||||||
|
- [3) Edge-Payload – Felder \& Semantik](#3-edge-payload--felder--semantik)
|
||||||
|
- [4) Typ-Registry (`config/types.yaml`)](#4-typ-registry-configtypesyaml)
|
||||||
|
- [4.1 Zweck](#41-zweck)
|
||||||
|
- [4.2 Beispiel (auslieferungsnah)](#42-beispiel-auslieferungsnah)
|
||||||
|
- [5) Der Retriever (Funktionaler Layer)](#5-der-retriever-funktionaler-layer)
|
||||||
|
- [5.1 Scoring-Modell](#51-scoring-modell)
|
||||||
|
- [5.2 Erklärbarkeit (Explainability) – WP04b](#52-erklärbarkeit-explainability--wp04b)
|
||||||
|
- [6) Context Intelligence \& Intent Router (WP06)](#6-context-intelligence--intent-router-wp06)
|
||||||
|
- [6.1 Das Problem: Statische vs. Dynamische Antworten](#61-das-problem-statische-vs-dynamische-antworten)
|
||||||
|
- [6.2 Der Intent-Router (Keyword \& Semantik)](#62-der-intent-router-keyword--semantik)
|
||||||
|
- [6.3 Strategic Retrieval (Injektion von Werten)](#63-strategic-retrieval-injektion-von-werten)
|
||||||
|
- [6.4 Reasoning (Das Gewissen)](#64-reasoning-das-gewissen)
|
||||||
|
- [7) Future Concepts: The Empathic Digital Twin (Ausblick)](#7-future-concepts-the-empathic-digital-twin-ausblick)
|
||||||
|
- [7.1 Antizipation durch Erfahrung](#71-antizipation-durch-erfahrung)
|
||||||
|
- [7.2 Empathie \& "Ich"-Modus](#72-empathie--ich-modus)
|
||||||
|
- [7.3 Glaubenssätze \& Rituale](#73-glaubenssätze--rituale)
|
||||||
|
- [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.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)
|
||||||
|
- [12) Frontmatter-Eigenschaften – Rolle \& Empfehlung](#12-frontmatter-eigenschaften--rolle--empfehlung)
|
||||||
|
- [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)
|
||||||
|
|
||||||
|
</details>
|
||||||
---
|
---
|
||||||
|
|
||||||
## 0) Zielbild & Grundprinzip
|
## 0) Zielbild & Grundprinzip
|
||||||
|
|
||||||
Mindnet wandelt Obsidian-Markdown-Notizen in einen **Graph aus Punkten und Kanten** um.
|
Mindnet wandelt Obsidian-Markdown-Notizen in einen **dynamischen Graphen aus Punkten und Kanten** um.
|
||||||
Die drei zentralen Artefakt-Sammlungen lauten:
|
Die drei zentralen Artefakt-Sammlungen lauten:
|
||||||
|
|
||||||
- `mindnet_notes` – genau **eine** Note pro Markdown-Datei (Metadaten & Hashes)
|
- `mindnet_notes` – genau **eine** Note pro Markdown-Datei (Metadaten & Hashes)
|
||||||
- `mindnet_chunks` – semantische Teilstücke einer Note (Fenster/„Chunks“)
|
- `mindnet_chunks` – semantische Teilstücke einer Note (Fenster/„Chunks“)
|
||||||
- `mindnet_edges` – gerichtete Beziehungen zwischen Knoten (Chunks/Notes)
|
- `mindnet_edges` – gerichtete Beziehungen zwischen Knoten (Chunks/Notes)
|
||||||
|
|
||||||
Die Import-Pipeline erzeugt diese Artefakte **deterministisch** und **idempotent** (erneute Läufe überschreiben konsistent statt zu duplizieren). Die Import-Schritte sind: *parse → chunk → edge → upsert*. :contentReference[oaicite:0]{index=0}
|
Die Import-Pipeline erzeugt diese Artefakte **deterministisch** und **idempotent** (erneute Läufe überschreiben konsistent statt zu duplizieren). Die Import-Schritte sind: *parse → chunk → edge → upsert*.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -23,51 +70,62 @@ Die Import-Pipeline erzeugt diese Artefakte **deterministisch** und **idempotent
|
|||||||
- Repräsentiert eine fachliche Einheit (z. B. *„Vector DB Basics“*, *„KI-Projekt“*).
|
- Repräsentiert eine fachliche Einheit (z. B. *„Vector DB Basics“*, *„KI-Projekt“*).
|
||||||
- Trägt Eigenschaften (Titel, Typ, Zeitstempel, optionale Policies).
|
- Trägt Eigenschaften (Titel, Typ, Zeitstempel, optionale Policies).
|
||||||
- **Typ** (*type*) steuert u. a. Chunk-Profil und Default-Relationen (siehe §4).
|
- **Typ** (*type*) steuert u. a. Chunk-Profil und Default-Relationen (siehe §4).
|
||||||
- **retriever_weight** und **chunk_profile** werden systematisch an Note **und** Chunks gespiegelt, damit der Retriever beides nutzen kann. :contentReference[oaicite:1]{index=1}
|
- **retriever_weight** und **chunk_profile** werden systematisch an Note **und** Chunks gespiegelt, damit der Retriever beides nutzen kann.
|
||||||
|
|
||||||
### 1.2 Chunk
|
### 1.2 Chunk
|
||||||
- Ausschnitt/Textfenster aus der Note, als eigenständiger Such-Anker.
|
- Ausschnitt/Textfenster aus der Note, als eigenständiger Such-Anker.
|
||||||
- Jeder Chunk gehört **genau einer** Note.
|
- Jeder Chunk gehört **genau einer** Note.
|
||||||
- Chunks bilden eine Sequenz (1…N) – das ermöglicht *next/prev*.
|
- Chunks bilden eine Sequenz (1…N) – das ermöglicht *next/prev*.
|
||||||
|
- **Neu in v2.2:** Alle Kanten entstehen ausschließlich zwischen Chunks (Scope="chunk"), nie zwischen Notes direkt. Notes dienen nur noch als Metadatencontainer.
|
||||||
|
|
||||||
> **Wichtig:** Chunking-Profile (short/medium/long) kommen aus `types.yaml` (per Note-Typ), können aber lokal überschrieben werden. Die effektiven Werte werden bei der Payload-Erzeugung bestimmt. :contentReference[oaicite:2]{index=2}
|
> **Wichtig:** Chunking-Profile (short/medium/long) kommen aus `types.yaml` (per Note-Typ), können aber lokal überschrieben werden. Die effektiven Werte werden bei der Payload-Erzeugung bestimmt.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2) Edges – fachliche Typen & Bedeutung
|
## 2) Edges – fachliche Typen & Bedeutung
|
||||||
|
|
||||||
Edges kodieren Beziehungen. Sie sind **gerichtet** und werden in `mindnet_edges` gespeichert.
|
Edges kodieren Beziehungen. Sie sind **gerichtet** und werden in `mindnet_edges` gespeichert. Die Erzeugung folgt einer strengen Priorität: **Inline > Callout > Defaults > Struktur**.
|
||||||
|
|
||||||
### 2.1 Struktur-Kanten
|
### 2.1 Struktur-Kanten (Das Skelett)
|
||||||
- **belongs_to**: *Chunk → Note* (Zuordnung)
|
- **belongs_to**: *Chunk → Note* (Zuordnung)
|
||||||
- **next / prev**: Kettenbeziehungen zwischen aufeinanderfolgenden Chunks derselben Note
|
- **next / prev**: Kettenbeziehungen zwischen aufeinanderfolgenden Chunks derselben Note.
|
||||||
→ ermöglichen „lineares Weiterlesen“ oder Kontextpfade in Antworten.
|
→ ermöglichen „lineares Weiterlesen“ oder Kontextpfade in Antworten.
|
||||||
Diese Kanten entstehen immer, unabhängig von Inhalten. :contentReference[oaicite:3]{index=3}
|
Diese Kanten entstehen immer, unabhängig von Inhalten.
|
||||||
|
|
||||||
### 2.2 Inhalts-Kanten (explizit)
|
### 2.2 Inhalts-Kanten (explizit)
|
||||||
- **references (chunk-scope)**: aus dem Textfenster des Chunks extrahierte Links.
|
Hier unterscheidet v2.2 präzise zwischen verschiedenen Quellen der Evidenz:
|
||||||
Standardquelle: **Wikilinks** `[[…]]` – einschließlich Varianten `[[id#anchor]]`, `[[id|label]]`.
|
|
||||||
→ Mindnet reduziert robust auf die Ziel-ID (Titel/ID-Normalisierung). :contentReference[oaicite:4]{index=4}
|
|
||||||
- **Explizite Inline-Relationen**: im Fließtext notierte Relationen, z. B.:
|
|
||||||
rel: similar_to [[Vector DB Basics]]
|
|
||||||
→ werden als Relation **similar_to** mit hoher Confidence materialisiert; *rule_id* `inline:rel`.
|
|
||||||
(Diese Form ist besonders kompakt in Obsidian editierbar.)
|
|
||||||
- **Callout-Edges** (optional):
|
|
||||||
> [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]]
|
|
||||||
→ erzeugt mehrere **related_to**-Kanten aus einer Zeile; *rule_id* `callout:edge`.
|
|
||||||
(Für kuratierte, sichtbare Linklisten am Notizende.)
|
|
||||||
|
|
||||||
> Alle expliziten Quellen (Wikilink, Inline-Rel, Callout) sind **gleichwertige Primärbelege** und werden als *provenance=explicit* geführt. Wo zutreffend, tragen Edges *rule_id* wie `explicit:wikilink`, `inline:rel`, `callout:edge`. :contentReference[oaicite:5]{index=5}
|
1. **Explizite Inline-Relationen (Höchste Priorität):**
|
||||||
|
Im Fließtext notierte, semantisch qualifizierte Relationen.
|
||||||
|
* Syntax: `[[rel:depends_on Embeddings 101]]`
|
||||||
|
* Fachliche Aussage: "Hängt ab von", "Ähnlich zu".
|
||||||
|
* *rule_id*: `inline:rel`
|
||||||
|
* *confidence*: ~0.95
|
||||||
|
|
||||||
### 2.3 Typ-basierte Default-Kanten (regelbasiert)
|
2. **Callout-Edges (Kuratierte Listen):**
|
||||||
|
Redaktionell gepflegte Listen am Ende einer Notiz (z.B. "Siehe auch").
|
||||||
|
* Syntax: `> [!edge] related_to: [[Vector DB Basics]]`
|
||||||
|
* *rule_id*: `callout:edge`
|
||||||
|
* *confidence*: ~0.90
|
||||||
|
|
||||||
|
3. **Wikilinks (Standard-Referenzen):**
|
||||||
|
Der klassische Obsidian-Link.
|
||||||
|
* Syntax: `[[Vector DB Basics]]`
|
||||||
|
* Typ: `references`
|
||||||
|
* *rule_id*: `explicit:wikilink`
|
||||||
|
* *confidence*: 1.0
|
||||||
|
|
||||||
|
> Alle expliziten Quellen (Wikilink, Inline-Rel, Callout) sind **Primärbelege**.
|
||||||
|
|
||||||
|
### 2.3 Typ-basierte Default-Kanten (Regelbasiert)
|
||||||
Jede Note hat einen *Typ* (z. B. `concept`, `project`, `profile`). In `config/types.yaml` definieren wir pro Typ **edge_defaults**, z. B.:
|
Jede Note hat einen *Typ* (z. B. `concept`, `project`, `profile`). In `config/types.yaml` definieren wir pro Typ **edge_defaults**, z. B.:
|
||||||
|
|
||||||
- `concept`: `["references","related_to"]`
|
- `concept`: `["references","related_to"]`
|
||||||
- `project`: `["references","depends_on"]`
|
- `project`: `["references","depends_on"]`
|
||||||
|
|
||||||
Regel: **Für jede gefundene explizite Referenz** (s. o.) werden **zusätzliche** Edges nach diesen Defaults erzeugt. Beispiel: Ein *project* mit `edge_defaults=["depends_on"]` erzeugt zu *jedem* explizit referenzierten Ziel **zusätzlich** eine `depends_on`-Kante.
|
Regel: **Für jede gefundene explizite Referenz** (s. o.) werden **zusätzliche** Edges nach diesen Defaults erzeugt.
|
||||||
Diese Kanten tragen *provenance=rule* und eine **rule_id** der Form
|
Beispiel: Ein *project* mit `edge_defaults=["depends_on"]` erzeugt zu *jedem* explizit referenzierten Ziel **zusätzlich** eine `depends_on`-Kante.
|
||||||
`edge_defaults:{note_type}:{relation}` (z. B. `edge_defaults:project:depends_on`). :contentReference[oaicite:6]{index=6}
|
Diese Kanten tragen *provenance=rule* und eine **rule_id** der Form `edge_defaults:{note_type}:{relation}` sowie eine geringere Confidence (~0.7).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -76,19 +134,17 @@ Diese Kanten tragen *provenance=rule* und eine **rule_id** der Form
|
|||||||
Jede Kante hat mindestens:
|
Jede Kante hat mindestens:
|
||||||
|
|
||||||
- `kind` – Beziehungsart *(belongs_to, next, prev, references, related_to, depends_on, similar_to, …)*
|
- `kind` – Beziehungsart *(belongs_to, next, prev, references, related_to, depends_on, similar_to, …)*
|
||||||
- `scope` – `"chunk"` (Standard) oder `"note"` (optional für Backlinks/Note-Scope)
|
- `scope` – `"chunk"` (Standard in v2.2)
|
||||||
- `source_id`, `target_id` – Quell-/Ziel-Knoten (Chunk- oder Note-ID)
|
- `source_id`, `target_id` – Quell-/Ziel-Knoten (Chunk-IDs oder Note-Titel bei unresolved Targets)
|
||||||
- `note_id` – **Owner-Note** (die Note, aus der die Kante stammt; dient der schnellen Löschung/Filterung)
|
- `note_id` – **Owner-Note** (die Note, aus der die Kante stammt)
|
||||||
|
|
||||||
Erweiterte/abgeleitete Felder (V2-Superset):
|
Erweiterte/abgeleitete Felder (WP03 Superset):
|
||||||
|
|
||||||
- `provenance` – `"explicit"` (Wikilink/Inline/Callout) oder `"rule"` (Typ-Defaults)
|
- `provenance` – `"explicit"` (Wikilink/Inline/Callout) oder `"rule"` (Typ-Defaults)
|
||||||
- `rule_id` – maschinenlesbare Regelquelle, z. B.
|
- `rule_id` – maschinenlesbare Regelquelle (z.B. `inline:rel`, `edge_defaults:project:depends_on`)
|
||||||
- `explicit:wikilink`, `inline:rel`, `callout:edge`
|
- `confidence` – 0.0–1.0; Heuristik zur Gewichtung im Scoring.
|
||||||
- `edge_defaults:{note_type}:{relation}`
|
|
||||||
- `confidence` – 0.0–1.0; Heuristik, z. B. `1.0` für Wikilinks/Backlinks, `0.95` für `inline:rel`, `0.7` für Typ-Defaults.
|
|
||||||
|
|
||||||
**Dedup-Schlüssel** (fachlich): Gleichlautende `(source_id, target_id, kind, scope, rule_id)` werden nicht mehrfach geschrieben. :contentReference[oaicite:7]{index=7}
|
**Dedup-Schlüssel** (fachlich): Gleichlautende `(source_id, target_id, kind, scope, rule_id)` werden nicht mehrfach geschrieben.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -99,7 +155,7 @@ Erweiterte/abgeleitete Felder (V2-Superset):
|
|||||||
- Liefert **retriever_weight** (Note-/Chunk-Gewichtung im Ranking) **pro Typ**
|
- Liefert **retriever_weight** (Note-/Chunk-Gewichtung im Ranking) **pro Typ**
|
||||||
- Definiert **edge_defaults** je Typ (s. o.)
|
- Definiert **edge_defaults** je Typ (s. o.)
|
||||||
|
|
||||||
Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. **Frontmatter-Overrides** (z. B. `retriever_weight`) werden respektiert; am Ende schreibt der Importer die **effektiven** Werte zuverlässig in Note- und Chunk-Payload. :contentReference[oaicite:8]{index=8}
|
Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. **Frontmatter-Overrides** für Profile werden in v2.2 weitgehend ignoriert zugunsten einer zentralen Governance in der YAML-Datei.
|
||||||
|
|
||||||
### 4.2 Beispiel (auslieferungsnah)
|
### 4.2 Beispiel (auslieferungsnah)
|
||||||
version: 1.0
|
version: 1.0
|
||||||
@@ -107,64 +163,185 @@ Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. *
|
|||||||
concept:
|
concept:
|
||||||
chunk_profile: medium
|
chunk_profile: medium
|
||||||
edge_defaults: ["references", "related_to"]
|
edge_defaults: ["references", "related_to"]
|
||||||
retriever_weight: 0.35
|
retriever_weight: 0.60
|
||||||
project:
|
project:
|
||||||
chunk_profile: long
|
chunk_profile: long
|
||||||
edge_defaults: ["references", "depends_on"]
|
edge_defaults: ["references", "depends_on"]
|
||||||
retriever_weight: 0.97
|
retriever_weight: 0.97
|
||||||
profile:
|
|
||||||
chunk_profile: long
|
|
||||||
edge_defaults: ["references", "depends_on"]
|
|
||||||
retriever_weight: 0.66
|
|
||||||
|
|
||||||
**Auflösung im Importer**
|
**Auflösung im Importer**
|
||||||
- `effective_chunk_profile(note_type, registry)` → `"short|medium|long"|None`
|
- `effective_chunk_profile(note_type, registry)` → `"short|medium|long"|None`
|
||||||
- `effective_retriever_weight(note_type, registry)` → `float|None`
|
- `effective_retriever_weight(note_type, registry)` → `float|None`
|
||||||
- Ergebnis wird in `note_payload` **und** `chunk_payloads` gespiegelt. :contentReference[oaicite:9]{index=9}
|
- Ergebnis wird in `note_payload` **und** `chunk_payloads` gespiegelt.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 5) Wie entstehen Edges aus Markdown?
|
## 5) Der Retriever (Funktionaler Layer)
|
||||||
|
|
||||||
### 5.1 Quelle „Wikilinks“ (Primärfall)
|
Der Retriever ist in v2.2 der zentrale Zugangspunkt. Er realisiert die **Hybride Suche**.
|
||||||
- Parser extrahiert alle `[[…]]` (Label/Anker werden auf die Ziel-ID reduziert).
|
|
||||||
- Pro Fund entsteht **eine** `references`-Kante (Chunk-Scope).
|
|
||||||
- Zusätzlich: Typ-Defaults (z. B. `depends_on`, `related_to`) pro Ziel. :contentReference[oaicite:10]{index=10}
|
|
||||||
|
|
||||||
### 5.2 Quelle „Inline-Relation“ (Optional, kompakt)
|
### 5.1 Scoring-Modell
|
||||||
- Im Fließtext markierte Relation, z. B.:
|
Die Relevanz eines Treffers ergibt sich nicht mehr nur aus Textähnlichkeit, sondern aus einer gewichteten Formel:
|
||||||
rel: similar_to [[Vector DB Basics]]
|
|
||||||
- Erzeugt `similar_to`-Kanten; *rule_id* `inline:rel`; `confidence≈0.95`.
|
|
||||||
- Geeignet für sparsame, gut lesbare Referenzierung. (Erfassung in der Chunk-Window-Analyse.) :contentReference[oaicite:11]{index=11}
|
|
||||||
|
|
||||||
### 5.3 Quelle „Callout-Edges“ (Optional, kuratiert)
|
total_score =
|
||||||
- Klar sichtbare, redaktionell gepflegte Liste am Ende einer Note:
|
semantic_weight * semantic_score
|
||||||
> [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]]
|
+ edge_weight * edge_bonus
|
||||||
- Erzeugt je Ziel eine `related_to`-Kante; *rule_id* `callout:edge`.
|
+ centrality_weight * centrality_bonus
|
||||||
- Eignet sich für „Leselisten“ und „Siehe auch“. (Zählung als *callout_total* in Reports, wo vorhanden.) :contentReference[oaicite:12]{index=12}
|
+ type_weight * retriever_weight
|
||||||
|
|
||||||
### 5.4 Struktur-Kanten
|
* **semantic_score:** Vektorähnlichkeit (Qdrant).
|
||||||
- `belongs_to` pro Chunk
|
* **retriever_weight:** Wichtigkeit des Typs (z.B. Projekte > Quellen).
|
||||||
- `next/prev` aus Nachbarbezug (aus Chunk-Sequenz/Neighbors) :contentReference[oaicite:13]{index=13}
|
* **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.
|
||||||
|
|
||||||
> **Hinweis zu Note-Scope:** Optional können zusätzlich Note-weite *references/backlinks* aus der Gesamtheit aller Chunk-Funde abgeleitet werden (Konfig-Flag/ENV). Das ist für globale Graph-Analysen nützlich, aber im Retrieval seltener erforderlich. :contentReference[oaicite:14]{index=14}
|
### 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) Context Intelligence & Intent Router (WP06)
|
||||||
|
|
||||||
|
Seit WP06 agiert Mindnet nicht mehr statisch, sondern passt seine Suchstrategie dem **Intent** (der Absicht) des Nutzers an. Dies ist die Transformation vom reinen Wissens-Abrufer zum strategischen Entscheidungspartner.
|
||||||
|
|
||||||
|
### 6.1 Das Problem: Statische vs. Dynamische Antworten
|
||||||
|
* **Früher (Pre-WP06):** Jede Frage ("Was ist X?" oder "Soll ich X?") wurde gleich behandelt -> Fakten-Retrieval.
|
||||||
|
* **Heute (WP06):** Das System erkennt, *was* der User will, und lädt unterschiedliche Wissensbausteine.
|
||||||
|
|
||||||
|
### 6.2 Der Intent-Router (Keyword & Semantik)
|
||||||
|
Der Router prüft vor jeder Antwort die Absicht über konfigurierbare Strategien (`config/decision_engine.yaml`):
|
||||||
|
|
||||||
|
1. **FACT:** Reine Wissensfrage ("Was ist Qdrant?"). → Standard RAG.
|
||||||
|
2. **DECISION:** Frage nach Rat oder Strategie ("Soll ich Qdrant nutzen?"). → Aktiviert die Decision Engine.
|
||||||
|
3. **EMPATHY:** Emotionale Zustände ("Ich bin gestresst"). → Aktiviert den empathischen Modus.
|
||||||
|
4. **CODING:** Technische Anfragen.
|
||||||
|
|
||||||
|
**Erkennung:**
|
||||||
|
* **Fast Path:** Prüfung auf Schlüsselwörter (z.B. "soll ich").
|
||||||
|
* **Slow Path (Smart Fallback):** Wenn kein Keyword passt, prüft ein LLM (Phi-3) die Semantik des Satzes.
|
||||||
|
|
||||||
|
### 6.3 Strategic Retrieval (Injektion von Werten)
|
||||||
|
Im Modus `DECISION` führt das System eine **zweite Suchstufe** aus. Es sucht nicht nur nach semantisch passenden Texten zur Frage, sondern erzwingt das Laden von strategischen Notizen wie:
|
||||||
|
* **Values (`type: value`):** Moralische Werte (z.B. "Privacy First").
|
||||||
|
* **Principles (`type: principle`):** Handlungsanweisungen.
|
||||||
|
* **Goals (`type: goal`):** Strategische Ziele.
|
||||||
|
|
||||||
|
Dies wird über **Late Binding** in `config/decision_engine.yaml` gesteuert. Neue Facetten der Persönlichkeit können dort konfiguriert werden, ohne den Code zu ändern.
|
||||||
|
|
||||||
|
### 6.4 Reasoning (Das Gewissen)
|
||||||
|
Das LLM erhält im Prompt die explizite Anweisung: *"Wäge die Fakten (aus der Suche) gegen die injizierten Werte ab."*
|
||||||
|
Dadurch entstehen Antworten, die nicht nur technisch korrekt sind, sondern subjektiv passend ("Tool X passt nicht zu deinem Ziel Z").
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7) Future Concepts: The Empathic Digital Twin (Ausblick)
|
||||||
|
|
||||||
|
Um Mindnet von einer Entscheidungsmaschine zu einem echten **Spiegel der Persönlichkeit** zu entwickeln, sind folgende Erweiterungen konzeptionell vorgesehen:
|
||||||
|
|
||||||
|
### 7.1 Antizipation durch Erfahrung
|
||||||
|
* **Konzept:** Das System soll Konsequenzen vorhersagen ("Was passiert, wenn...?").
|
||||||
|
* **Umsetzung:** Neben Werten werden vergangene Erfahrungen (`type: experience`) geladen.
|
||||||
|
* **Logik:** *"In einer ähnlichen Situation (Projekt A) hat Entscheidung X zu Ergebnis Y geführt."*
|
||||||
|
|
||||||
|
### 7.2 Empathie & "Ich"-Modus
|
||||||
|
* **Konzept:** Das System antwortet nicht wie ein Roboter, sondern im Tonfall und Stil des Nutzers.
|
||||||
|
* **Umsetzung (Few-Shot Prompting):** Der System-Prompt wird dynamisch mit Beispielen gefüttert, wie der Nutzer typischerweise auf E-Mails oder Fragen antwortet.
|
||||||
|
* **Datenbasis:** `type: profile` oder `type: manifesto` definieren das Selbstbild.
|
||||||
|
|
||||||
|
### 7.3 Glaubenssätze & Rituale
|
||||||
|
* **Konzept:** Berücksichtigung weicher Faktoren und Gewohnheiten.
|
||||||
|
* **Umsetzung:** Erweiterung der `decision_engine.yaml` um `inject_types: ["belief", "ritual"]`.
|
||||||
|
* **Szenario:** Bei Terminplanungen werden Rituale ("Keine Meetings vor 10 Uhr") automatisch als harte Restriktion gegen Anfragen geprüft.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8) Erweiterbarkeit & Teaching (Context Intelligence)
|
||||||
|
|
||||||
|
Mindnet lernt nicht durch klassisches Training (Fine-Tuning), sondern durch **Konfiguration**, **Vernetzung** und **Prompting**. Dies ist das **"Teach-the-AI" Paradigma**: Wenn du dem System ein neues Konzept beibringen willst, musst du an drei Stellen eingreifen.
|
||||||
|
|
||||||
|
### A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)
|
||||||
|
|
||||||
|
1. **Physik definieren (`config/types.yaml`)**
|
||||||
|
Steuere, wie schwer der Inhalt wiegt und wie er vernetzt wird.
|
||||||
|
```yaml
|
||||||
|
risk:
|
||||||
|
chunk_profile: short # Risiken sind prägnant
|
||||||
|
retriever_weight: 0.90 # Hohe Priorität im Ranking
|
||||||
|
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
|
||||||
|
```
|
||||||
|
*Effekt:* Der Retriever spült diese Notizen bei relevanten Anfragen nach oben.
|
||||||
|
|
||||||
|
2. **Semantik erklären (`config/prompts.yaml` / `decision_engine.yaml`)**
|
||||||
|
Bringe dem LLM bei, wie es mit diesem Typ umgehen soll. Füge `risk` zur `DECISION`-Strategie hinzu (`inject_types`), damit es bei Entscheidungen geladen wird.
|
||||||
|
|
||||||
|
### B. Workflow: Neue Beziehungen nutzen (z. B. `beeinflusst_von`)
|
||||||
|
|
||||||
|
Beziehungen sind der Klebstoff für logische Schlussfolgerungen.
|
||||||
|
|
||||||
|
1. **Erfassung im Vault (Markdown)**
|
||||||
|
Nutze die Inline-Syntax. Du musst nichts vorab definieren.
|
||||||
|
> "Die Entscheidung für Qdrant wurde [[rel:beeinflusst_von Budgetkürzung 2024]]."
|
||||||
|
|
||||||
|
2. **Gewichtung justieren (`config/retriever.yaml`)**
|
||||||
|
Standardmäßig sind alle Kanten gleich `1.0`. Wenn Kausalität wichtiger ist als Ähnlichkeit, definiere dies hier:
|
||||||
|
```yaml
|
||||||
|
retriever:
|
||||||
|
edge_weights:
|
||||||
|
beeinflusst_von: 1.5 # Starker Boost: Zieht Ursachen in den Kontext
|
||||||
|
related_to: 0.5 # Schwacher Boost: Nur "nice to know"
|
||||||
|
```
|
||||||
|
*Effekt:* Bei der Frage nach "Qdrant" landet die "Budgetkürzung" (Ursache) im Kontext, weil die Kante stark ist.
|
||||||
|
|
||||||
|
3. **Interpretation (Prompting)**
|
||||||
|
Das LLM erkennt im RAG-Kontext: `Qdrant --[beeinflusst_von]--> Budgetkürzung`.
|
||||||
|
Es kann daraus den Satz formulieren: *"Die Wahl fiel vermutlich aufgrund der Budgetkürzung auf Qdrant."*
|
||||||
|
|
||||||
|
**Fazit:** Nur wenn **Daten** (Vault), **Physik** (Config) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9) Feedback & Lernen – WP04c
|
||||||
|
|
||||||
|
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
|
||||||
|
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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10) Confidence & Provenance – wozu?
|
||||||
|
|
||||||
Der Retriever kann Edges gewichten:
|
Der Retriever kann Edges gewichten:
|
||||||
- **provenance**: *explicit* > *rule*
|
- **provenance**: *explicit* > *rule*
|
||||||
- **confidence**: numerische Feinsteuerung (z. B. Inline-Relation etwas höher, Defaults etwas niedriger)
|
- **confidence**: numerische Feinsteuerung
|
||||||
- **retriever_weight (Note/Chunk)**: skaliert die Relevanz des gesamten Knotens
|
- **retriever_weight (Note/Chunk)**: skaliert die Relevanz des gesamten Knotens
|
||||||
|
|
||||||
Eine typische Gewichtung (konfigurierbar) ist:
|
Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
|
||||||
explicit: 1.0, rule: 0.8, default_resolved: 0.6, default: 0.2
|
`explicit: 1.0`, `rule: 0.8`. Damit bevorzugt der Graph **kuratiertes Wissen** (explizit notierte Links) vor „erweiterten“ Default-Ableitungen.
|
||||||
Damit bevorzugt der Graph **kuratiertes Wissen** (explizit notierte Links) vor „erweiterten“ Default-Ableitungen. :contentReference[oaicite:15]{index=15}
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 7) Semantik ausgewählter `kind`-Werte
|
## 11) Semantik ausgewählter `kind`-Werte
|
||||||
|
|
||||||
- `references` – „Nutzt/erwähnt“; neutral, aber stützend für Kontext.
|
- `references` – „Nutzt/erwähnt“; neutral, aber stützend für Kontext.
|
||||||
- `related_to` – Ähnlichkeit/Verwandtschaft (symmetrisch interpretierbar).
|
- `related_to` – Ähnlichkeit/Verwandtschaft (symmetrisch interpretierbar).
|
||||||
@@ -172,120 +349,71 @@ Damit bevorzugt der Graph **kuratiertes Wissen** (explizit notierte Links) vor
|
|||||||
- `depends_on` – fachliche Abhängigkeit (z. B. „Projekt X hängt von Y ab“).
|
- `depends_on` – fachliche Abhängigkeit (z. B. „Projekt X hängt von Y ab“).
|
||||||
- `belongs_to`, `next`, `prev` – Struktur.
|
- `belongs_to`, `next`, `prev` – Struktur.
|
||||||
|
|
||||||
> Symmetrische Relationen (z. B. `related_to`, `similar_to`) können **explizit** nur einseitig notiert sein, aber im Retriever beidseitig interpretiert werden (z. B. Query-Zeit-Expansion), um Redundanz im Vault zu vermeiden. :contentReference[oaicite:16]{index=16}
|
> Symmetrische Relationen (z. B. `related_to`, `similar_to`) können **explizit** nur einseitig notiert sein, aber im Retriever beidseitig interpretiert werden.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 8) Frontmatter-Eigenschaften – Rolle & Empfehlung
|
## 12) Frontmatter-Eigenschaften – Rolle & Empfehlung
|
||||||
|
|
||||||
Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
|
Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
|
||||||
- **type** – steuert Typ-Defaults via Registry (Pflicht für differenziertes Verhalten).
|
- **type** – steuert Typ-Defaults via Registry (Pflicht für differenziertes Verhalten).
|
||||||
- **retriever_weight** *(optional)* – kann typbasierte Defaults überschreiben.
|
- **tags** – für klassische Filterung.
|
||||||
- **chunk_profile** *(optional)* – kann typbasierte Defaults überschreiben.
|
- **retriever_weight / chunk_profile** – Sollten **nicht** manuell gesetzt werden (Best Practice: `types.yaml` nutzen).
|
||||||
- **links** *(optional, Bestandskompatibilität)* – wenn vorhanden (z. B. `depends_on: …`), können sie als explizite Kanten materialisiert werden; die Pflege in freiem Text (Inline/Callout) ist jedoch **benutzerfreundlicher** und weniger fehleranfällig.
|
- **links** – Veraltet. Bitte Links primär über Text (Wikilink/Inline/Callout) pflegen.
|
||||||
|
|
||||||
Empfehlung: **Links primär über Text (Wikilink/Inline/Callout) pflegen**, nicht als Properties. Die Registry regelt Standards; Properties dienen nur gezielten Ausnahmen. :contentReference[oaicite:17]{index=17}
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 9) Lösch-/Update-Garantien (Idempotenz)
|
## 13) Lösch-/Update-Garantien (Idempotenz)
|
||||||
|
|
||||||
- Jede Note hat einen stabilen **note_id** (Frontmatter/Hash).
|
- 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.
|
- 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.
|
||||||
- Es gibt Abkürzungen für „fehlertolerante Rebuilds“: *Existenz-Checks* statt Full-Scan. :contentReference[oaicite:18]{index=18}
|
- Die Import-Skripte unterstützen Modi wie `--purge-before-upsert` und `--sync-deletes`, um den Graph sauber zu halten.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 10) Beispiel – Von Markdown zu Kanten
|
## 14) Beispiel – Von Markdown zu Kanten (v2.2)
|
||||||
|
|
||||||
**Markdown (Auszug)**
|
**Markdown (Auszug)**
|
||||||
# Relations Showcase
|
# Relations Showcase
|
||||||
…
|
…
|
||||||
rel: similar_to [[Vector DB Basics]]
|
Wir nutzen [[rel:depends_on Qdrant Vektordatenbank]] für die Suche.
|
||||||
…
|
…
|
||||||
[[Embeddings 101]]
|
Siehe auch: [[Embeddings 101]]
|
||||||
|
|
||||||
> [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]]
|
> [!edge] related_to: [[Vector DB Basics]]
|
||||||
|
|
||||||
**Ergebnis (fachlich)**
|
**Ergebnis (fachlich)**
|
||||||
- `references(Chunk→Vector DB Basics)` + `references(Chunk→Embeddings 101)`
|
1. `depends_on(Chunk→Qdrant)` mit `rule_id=inline:rel`, `confidence≈0.95`.
|
||||||
- `similar_to(Chunk→Vector DB Basics)` mit `rule_id=inline:rel`, `confidence≈0.95`
|
2. `references(Chunk→Embeddings 101)` mit `rule_id=explicit:wikilink`, `confidence=1.0`.
|
||||||
- `related_to(Chunk→Vector DB Basics)` und `related_to(Chunk→Embeddings 101)`
|
3. `related_to(Chunk→Vector DB Basics)` via Callout; `rule_id=callout:edge`, `confidence≈0.90`.
|
||||||
via Callout; `rule_id=callout:edge`
|
4. **Typ-Defaults:** Falls die Note vom Typ `project` ist, entstehen zusätzlich `depends_on`-Kanten zu den Zielen aus (2) und (3).
|
||||||
- Zusätzliche **Typ-Defaults** je Quell-Typ, z. B. `edge_defaults:concept:related_to` → weitere `related_to`-Kanten
|
|
||||||
|
|
||||||
*Strukturkanten* (`belongs_to`, `next/prev`) fallen wie üblich an. (Die tatsächlichen Zähllogiken erscheinen im Import-Report/Smoke-Tests.) :contentReference[oaicite:19]{index=19}
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 11) Abfrage-Implikationen (fachlich)
|
## 15) Referenzen (Projektdateien & Leitlinien)
|
||||||
|
|
||||||
Retriever und Query-Layer berücksichtigen:
|
- Import-Pipeline & Registry-Auflösung: `scripts/import_markdown.py`.
|
||||||
1) **Knoten-Gewicht** (`retriever_weight`) aus Typ/Property (Note & Chunk).
|
- Kantenbildung (V2-Logic): `app/core/derive_edges.py`.
|
||||||
2) **Edge-Provenance/Confidence** – explizit > regelbasiert; höhere Confidence bevorzugt.
|
- Typ-Registry: `config/types.yaml` & `TYPE_REGISTRY_MANUAL.md`.
|
||||||
3) **Edge-Topologie** – z. B. 1-Hop-Nachbarschaft, Sequenzpfade (`next/prev`), Backlinks (optional).
|
- Retriever-Scoring & Explanation: `app/core/retriever.py`.
|
||||||
4) **Policy-Filter** – Privacy, Tags, Created usw. via Payload-Indizes.
|
- Persönlichkeit & Chat: `config/prompts.yaml` & `app/routers/chat.py`.
|
||||||
|
- Decision Engine: `config/decision_engine.yaml`.
|
||||||
Die Abfrage kann so z. B. Ergebnisse bevorzugen, die **explizit** in einem *Projekt* als `depends_on` genannt sind – und nur nachrangig solche, die „typbedingt“ (`edge_defaults`) ähnlich/abhängig sind. :contentReference[oaicite:20]{index=20}
|
- Logging Service: `app/services/feedback_service.py`.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 12) Qualitäts- und Testkriterien (fachlich)
|
## 16) Workpackage Status (v2.3.1)
|
||||||
|
|
||||||
- **Keine Duplikate** gleicher `(src, relation, dst)` in der Collectionsicht (Dedup).
|
Aktueller Implementierungsstand der Module.
|
||||||
- **Explizite Links** werden vollständig materialisiert (*explicit_total*).
|
|
||||||
- **Typ-Defaults** ergänzen, aber überdecken nicht – Counts bleiben plausibel (*defaults_total*).
|
|
||||||
- **Inline/Callout** werden separat quantifiziert (*inline_total*, *callout_total*), damit Redaktionen ihre Pflegewirkung beobachten können. :contentReference[oaicite:21]{index=21}
|
|
||||||
|
|
||||||
---
|
| WP | Titel | Status | Anmerkung |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
## 13) Praxisempfehlungen für den Vault
|
| **WP01** | Knowledge Design | 🟢 Live | Typen, Frontmatter definiert. |
|
||||||
|
| **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. |
|
||||||
1) **Wikilinks** überall, wo eine inhaltliche Nennung stattfindet.
|
| **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. |
|
||||||
2) Für **gezielte Relationen** (Ähnlichkeit/Abhängigkeit) kurze **Inline-Rel**-Zeilen; z. B.:
|
| **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). |
|
||||||
rel: similar_to [[X]]
|
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
|
||||||
rel: related_to [[Y]] [[Z]]
|
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
|
||||||
3) Am Notizende **Callout-Edges** für kuratierte Überblicksblöcke:
|
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
|
||||||
> [!edge] related_to: [[X]] [[Y]]
|
| **WP06** | Decision Engine | 🟢 Live | Intent-Router & Strategic Retrieval. |
|
||||||
4) **Properties** schlank halten: mindestens `type`, optional `retriever_weight`/`chunk_profile`.
|
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
|
||||||
5) **types.yaml** pflegen (zentrale Governance): *Welche Typen gibt es? Welche Default-Relationen sind fachlich sinnvoll?*
|
|
||||||
6) **Regelmäßige Smoke-Tests/Reports** prüfen die Kanten-Counts und Provenance-Verteilung. :contentReference[oaicite:22]{index=22}
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 14) Referenzen (Projektdateien & Leitlinien)
|
|
||||||
|
|
||||||
- Import-Pipeline & Registry-Auflösung (Importer, Flags, Idempotenz): `scripts/import_markdown.py`. :contentReference[oaicite:23]{index=23}
|
|
||||||
- Robuste Kantenbildung (Wikilinks, Struktur, optionale Note-Scope): `app/core/derive_edges.py` (v1.4+). :contentReference[oaicite:24]{index=24}
|
|
||||||
- V2-Edge-Superset (Provenance, rule_id, Confidence, Typ-Defaults): `app/core/edges.py` (v2.0+). :contentReference[oaicite:25]{index=25}
|
|
||||||
- Typ-Registry laden/auflösen (Fallbacks, Effektivwerte): Import-Helper / *Type-Registry*-Hilfsfunktionen. :contentReference[oaicite:26]{index=26}
|
|
||||||
- Test-/Playbook-Leitplanken (Policies, KPIs, Roadmap): *Implementation Playbook*. :contentReference[oaicite:27]{index=27}
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 15) Anhang – Mini-Beispiel einer Projekt-Note (verkürzt)
|
|
||||||
|
|
||||||
---
|
|
||||||
id: 20251110-ki-trainerassistent-projekt-56d2aa
|
|
||||||
title: KI Trainerassistent (Projekt)
|
|
||||||
type: project
|
|
||||||
retriever_weight: 1.0 # optional Override
|
|
||||||
chunk_profile: default # optional Override
|
|
||||||
---
|
|
||||||
|
|
||||||
# KI Trainerassistent (Projekt)
|
|
||||||
|
|
||||||
Wir nutzen [[Qdrant Vektordatenbank]] und [[Ollama LLM]] …
|
|
||||||
|
|
||||||
rel: depends_on [[Qdrant Vektordatenbank]]
|
|
||||||
rel: related_to [[Ollama LLM]]
|
|
||||||
|
|
||||||
> [!edge] depends_on: [[Qdrant Vektordatenbank]]
|
|
||||||
> [!edge] related_to: [[Ollama LLM]]
|
|
||||||
|
|
||||||
*Erwartung*:
|
|
||||||
- `references` (Wikilinks) auf **beide** Ziele
|
|
||||||
- `depends_on` & `related_to` via **Inline** und **Callout** (provenance=`explicit`, rule_id `inline:rel`/`callout:edge`)
|
|
||||||
- Zusätzlich **Typ-Defaults** aus `types.yaml` für `project` (z. B. weitere `depends_on`) – provenance=`rule`, `rule_id=edge_defaults:project:depends_on`. :contentReference[oaicite:28]{index=28}
|
|
||||||
|
|
||||||
---
|
|
||||||
@@ -1,699 +1,356 @@
|
|||||||
# Mindnet – Technische Architektur (V2, Stand: 2025-11-xx)
|
# Mindnet v2.2 – Technische Architektur
|
||||||
|
**Datei:** `docs/mindnet_technical_architecture_v2.2.md`
|
||||||
|
**Stand:** 2025-12-09
|
||||||
|
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
|
||||||
|
**Quellen:** `Programmplan_V2.2.md`, `Handbuch.md`, `chunking_strategy.md`, `wp04_retriever_scoring.md`.
|
||||||
|
|
||||||
> **Ziel dieses Dokuments:**
|
> **Ziel dieses Dokuments:**
|
||||||
> Vollständige, konsolidierte Beschreibung der aktuellen technischen Architektur von **Mindnet V2** – insbesondere der Verarbeitung von Markdown-Notizen, des Chunkings, der Kantenableitung (Edges) inkl. `rule_id` / `confidence` und der Speicherung in Qdrant.
|
> Vollständige Beschreibung der technischen Architektur inkl. Graph-Datenbank, Retrieval-Logik und der **neuen RAG-Komponenten (Decision Engine & Hybrid Router)**.
|
||||||
> Das Dokument bildet den **aktuellen Implementierungsstand** ab, nicht mehr gültige Annahmen sind bereinigt, neue Konzepte (Typ-Defaults, Inline-Relationen, Edges-Schema) sind integriert.
|
|
||||||
|
|
||||||
|
---
|
||||||
|
<details>
|
||||||
|
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
|
||||||
|
|
||||||
|
- [Mindnet v2.2 – Technische Architektur](#mindnet-v22--technische-architektur)
|
||||||
|
- [](#)
|
||||||
|
- [1. Systemüberblick](#1-systemüberblick)
|
||||||
|
- [1.1 Architektur-Zielbild](#11-architektur-zielbild)
|
||||||
|
- [1.2 Verzeichnisstruktur \& Komponenten (Post-WP06)](#12-verzeichnisstruktur--komponenten-post-wp06)
|
||||||
|
- [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)
|
||||||
|
- [2.3 Edges Collection (`<prefix>_edges`)](#23-edges-collection-prefix_edges)
|
||||||
|
- [3. Konfiguration](#3-konfiguration)
|
||||||
|
- [3.1 Typ-Registry (`config/types.yaml`)](#31-typ-registry-configtypesyaml)
|
||||||
|
- [3.2 Retriever-Config (`config/retriever.yaml`)](#32-retriever-config-configretrieveryaml)
|
||||||
|
- [3.3 Decision Engine (`config/decision_engine.yaml`)](#33-decision-engine-configdecision_engineyaml)
|
||||||
|
- [3.4 Prompts (`config/prompts.yaml`)](#34-prompts-configpromptsyaml)
|
||||||
|
- [3.5 Environment (`.env`)](#35-environment-env)
|
||||||
|
- [4. Import-Pipeline (Markdown → Qdrant)](#4-import-pipeline-markdown--qdrant)
|
||||||
|
- [4.1 Verarbeitungsschritte](#41-verarbeitungsschritte)
|
||||||
|
- [5. Retriever-Architektur \& Scoring](#5-retriever-architektur--scoring)
|
||||||
|
- [5.1 Betriebsmodi](#51-betriebsmodi)
|
||||||
|
- [5.2 Scoring-Formel (WP04a)](#52-scoring-formel-wp04a)
|
||||||
|
- [5.3 Explanation Layer (WP04b)](#53-explanation-layer-wp04b)
|
||||||
|
- [5.4 Graph-Expansion](#54-graph-expansion)
|
||||||
|
- [6. RAG \& Chat Architektur (WP06 Hybrid Router)](#6-rag--chat-architektur-wp06-hybrid-router)
|
||||||
|
- [6.1 Architektur-Pattern: Intent Router](#61-architektur-pattern-intent-router)
|
||||||
|
- [6.2 Schritt 1: Intent Detection (Hybrid)](#62-schritt-1-intent-detection-hybrid)
|
||||||
|
- [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)
|
||||||
|
|
||||||
|
|
||||||
|
</details>
|
||||||
---
|
---
|
||||||
|
|
||||||
## 1. Systemüberblick
|
## 1. Systemüberblick
|
||||||
|
|
||||||
### 1.1 Zielbild
|
### 1.1 Architektur-Zielbild
|
||||||
|
Mindnet ist ein **lokales RAG-System (Retrieval Augmented Generation)**.
|
||||||
|
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.
|
||||||
|
|
||||||
Mindnet ist ein **persönliches Wissensnetz**. Technisch bedeutet das:
|
Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsgetrieben** (`types.yaml`, `retriever.yaml`, `decision_engine.yaml`, `prompts.yaml`).
|
||||||
|
|
||||||
- Markdown-Notizen in einem Vault (Obsidian-kompatibel) werden
|
### 1.2 Verzeichnisstruktur & Komponenten (Post-WP06)
|
||||||
- geparst (Frontmatter + Body),
|
|
||||||
- in **Notes**, **Chunks** und **Edges** überführt,
|
|
||||||
- in **Qdrant** als drei Collections abgelegt:
|
|
||||||
- `<prefix>_notes`
|
|
||||||
- `<prefix>_chunks`
|
|
||||||
- `<prefix>_edges`.
|
|
||||||
|
|
||||||
- Das System ist so konzipiert, dass es:
|
/mindnet/
|
||||||
- **deterministisch** arbeitet (IDs, Chunks, Kanten),
|
├── app/
|
||||||
- über `types.yaml` **konfigurierbar** ist,
|
│ ├── main.py # FastAPI Einstiegspunkt
|
||||||
- später von einem LLM-basieren Agenten als **Graph-Retriever** genutzt werden kann.
|
│ ├── core/
|
||||||
|
│ │ ├── qdrant.py # Client-Factory & Connection
|
||||||
|
│ │ ├── qdrant_points.py # Low-Level Point Operations (Upsert/Delete)
|
||||||
|
│ │ ├── note_payload.py # Bau der Note-Objekte
|
||||||
|
│ │ ├── chunk_payload.py # Bau der Chunk-Objekte
|
||||||
|
│ │ ├── chunker.py # Text-Zerlegung (Profiling)
|
||||||
|
│ │ ├── edges.py # Edge-Datenstrukturen
|
||||||
|
│ │ ├── derive_edges.py # Logik der Kantenableitung (WP03)
|
||||||
|
│ │ ├── graph_adapter.py # Subgraph & Reverse-Lookup (WP04b)
|
||||||
|
│ │ └── retriever.py # Scoring, Expansion & Explanation (WP04a/b)
|
||||||
|
│ ├── models/ # Pydantic DTOs
|
||||||
|
│ ├── routers/
|
||||||
|
│ │ ├── query.py # Such-Endpunkt
|
||||||
|
│ │ ├── chat.py # Hybrid Router & Decision Engine (WP06)
|
||||||
|
│ │ ├── feedback.py # Feedback-Endpunkt (WP04c)
|
||||||
|
│ │ └── ...
|
||||||
|
│ ├── services/
|
||||||
|
│ │ ├── llm_service.py # Ollama Client mit Timeout & Raw-Mode
|
||||||
|
│ │ ├── feedback_service.py # JSONL Logging (WP04c)
|
||||||
|
│ │ └── embeddings_client.py
|
||||||
|
├── config/
|
||||||
|
│ ├── types.yaml # Typ-Definitionen (Import-Zeit)
|
||||||
|
│ ├── retriever.yaml # Scoring-Gewichte (Laufzeit)
|
||||||
|
│ ├── decision_engine.yaml # Strategien & Keywords (WP06)
|
||||||
|
│ └── prompts.yaml # LLM System-Prompts & Templates (WP06)
|
||||||
|
├── data/
|
||||||
|
│ └── logs/ # Lokale JSONL-Logs (WP04c)
|
||||||
|
├── scripts/
|
||||||
|
│ ├── import_markdown.py # Haupt-Importer CLI
|
||||||
|
│ ├── payload_dryrun.py # Diagnose: JSON-Generierung ohne DB
|
||||||
|
│ └── edges_full_check.py # Diagnose: Graph-Integrität
|
||||||
|
└── tests/ # Pytest Suite
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 1.2 Verzeichnisstruktur (Server)
|
## 2. Datenmodell & Collections (Qdrant)
|
||||||
|
|
||||||
/home/llmadmin/mindnet/:
|
Das Datenmodell verteilt sich auf drei Collections, definiert durch `COLLECTION_PREFIX` (Standard: `mindnet`).
|
||||||
|
|
||||||
- **/app**
|
### 2.1 Notes Collection (`<prefix>_notes`)
|
||||||
- `main.py` – FastAPI-App / Einstieg
|
Repräsentiert die Metadaten einer Datei.
|
||||||
- **/app/core**
|
* **Zweck:** Filterung, Metadaten-Haltung, Vererbung von Eigenschaften an Chunks.
|
||||||
- `qdrant.py` – QdrantConfig, Client-Factory, Collection-Management
|
* **Schema (Payload):**
|
||||||
- `qdrant_points.py` – Upserts / Deletes / Queries auf Punktebene
|
|
||||||
- `note_payload.py` – Bau von Note-Payloads
|
| Feld | Datentyp | Beschreibung | Herkunft |
|
||||||
- `chunk_payload.py` – Bau von Chunk-Payloads
|
| :--- | :--- | :--- | :--- |
|
||||||
- `chunker.py` – Chunking-Logik
|
| `note_id` | Keyword | Stabile ID (UUIDv5 oder Slug). | Frontmatter |
|
||||||
- `edges.py` – Datenstruktur & Hilfsfunktionen für Edges
|
| `title` | Text | Titel der Notiz. | Frontmatter |
|
||||||
- `derive_edges.py` – Ableitung von Edges aus Text und Typen
|
| `type` | Keyword | Logischer Typ (z.B. `concept`). | `types.yaml` Resolver |
|
||||||
- **/app/models**
|
| `retriever_weight` | Float | Wichtigkeit im Retrieval. | `types.yaml` |
|
||||||
- `dto.py` – DTOs für API / Services
|
| `chunk_profile` | Keyword | Genutztes Chunking-Profil. | `types.yaml` |
|
||||||
- **/app/routers**
|
| `edge_defaults` | List[Str] | Aktive Default-Relationen. | `types.yaml` |
|
||||||
- `qdrant_router.py` – API-Layer Richtung Qdrant
|
| `tags` | List[Kw] | Tags zur Filterung. | Frontmatter |
|
||||||
- **/app/services**
|
| `updated` | Integer | Zeitstempel (z.B. YYYYMMDD...). | File Stats |
|
||||||
- `llm_ollama.py` – Anbindung an Ollama-LLM
|
| `fulltext` | Text | Gesamter Inhalt (für Export/Rekonstruktion). | Body |
|
||||||
- `embeddings_client.py` – Embedding-Service (z. B. Ollama / lokaler Dienst)
|
|
||||||
- **/config**
|
### 2.2 Chunks Collection (`<prefix>_chunks`)
|
||||||
- `types.yaml` – Typdefinitionen inkl. Chunk-Profilen und Edge-Defaults
|
Die atomaren Sucheinheiten.
|
||||||
- **/scripts**
|
* **Zweck:** Vektorsuche (Embeddings), Granulares Ergebnis.
|
||||||
- `import_markdown.py` – Hauptimporter für Vault
|
* **Schema (Payload):**
|
||||||
- `reset_qdrant.py` – Collections löschen/neu anlegen (inkl. Indizes)
|
|
||||||
- `setup_mindnet_collections.py` – Collection-Setup (historisch / Hilfsskript)
|
| Feld | Datentyp | Beschreibung |
|
||||||
- diverse Diagnose- und Testskripte, z. B.
|
| :--- | :--- | :--- |
|
||||||
- `payload_dryrun.py`
|
| `chunk_id` | Keyword | Deterministisch: `{note_id}#c{index:02d}`. |
|
||||||
- `edges_full_check.py`
|
| `note_id` | Keyword | Referenz zur Note. |
|
||||||
- **/tests**
|
| `type` | Keyword | **Kopie des Note-Typs** (Denormalisiert für Filter). |
|
||||||
- `test_edges_smoke.py` – einfache Edge-Smoke-Tests
|
| `text` | Text | **Reiner Inhalt** (ohne Overlap). Anzeige-Text. |
|
||||||
- `test_edges_all.py` – umfassendere Checks (Counts, Plausibilität)
|
| `window` | Text | **Kontext-Fenster** (mit Overlap). Embedding-Basis. |
|
||||||
- `ensure_indexes_and_show.py`, `assert_payload_schema.py` – Schema/Index-Checks
|
| `ord` | Integer | Sortierreihenfolge (1..N). |
|
||||||
- **/vault**
|
| `retriever_weight` | Float | Vererbt von Note. |
|
||||||
- produktives Vault (Obsidian)
|
| `chunk_profile` | Keyword | Vererbt von Note. |
|
||||||
- **/mindnet_v2_test_vault**
|
| `neighbors_prev` | List[Str] | ID des Vorgänger-Chunks. |
|
||||||
- Test-Vault für V2-Funktionen (Chunking, Edges, Typ-Defaults)
|
| `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.
|
||||||
|
* **Schema (Payload):**
|
||||||
|
|
||||||
|
| Feld | Datentyp | Beschreibung | Wertebereich (Bsp.) |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| `edge_id` | Keyword | Hash aus (src, dst, kind). | |
|
||||||
|
| `source_id` | Keyword | ID des Start-Chunks. | |
|
||||||
|
| `target_id` | Keyword | ID des Ziel-Chunks (oder Note-Titel). | |
|
||||||
|
| `note_id` | Keyword | Note, die diese Kante definiert. | |
|
||||||
|
| `kind` | Keyword | Art der Beziehung. | `references`, `depends_on`, `next` |
|
||||||
|
| `scope` | Keyword | Geltungsbereich. | Immer `"chunk"` (v2.2). |
|
||||||
|
| `rule_id` | Keyword | Herkunftsregel. | `explicit:wikilink`, `inline:rel` |
|
||||||
|
| `confidence` | Float | Vertrauenswürdigkeit (0.0-1.0). | 1.0, 0.95, 0.7 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2. Datenmodell & Collections
|
## 3. Konfiguration
|
||||||
|
|
||||||
### 2.1 Note, Chunk, Edge – Begriffe
|
Die Logik ist ausgelagert in YAML-Dateien.
|
||||||
|
|
||||||
- **Note**
|
### 3.1 Typ-Registry (`config/types.yaml`)
|
||||||
Entspricht einer Markdown-Datei mit YAML-Frontmatter (`id`, `title`, `type`, …).
|
Steuert den Import-Prozess.
|
||||||
In Qdrant als ein Punkt in `<prefix>_notes`.
|
* **Priorität:** Frontmatter > Pfad > Default.
|
||||||
|
* **Inhalt (Beispiel):**
|
||||||
- **Chunk**
|
|
||||||
Ein Abschnitt einer Note (z. B. Absatz, Überschrifts-Block, Sliding Window).
|
|
||||||
In Qdrant als Punkt in `<prefix>_chunks`.
|
|
||||||
|
|
||||||
- **Edge**
|
|
||||||
Eine gerichtete Kante, die eine Beziehung zwischen:
|
|
||||||
- zwei Chunks,
|
|
||||||
- Chunk ↔ Note,
|
|
||||||
- oder (konzeptionell) Note ↔ Note beschreibt.
|
|
||||||
Gespeichert in `<prefix>_edges`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2.2 Qdrant Collections (Stand V2)
|
|
||||||
|
|
||||||
**Namenskonvention:**
|
|
||||||
Prefix aus ENV (`COLLECTION_PREFIX`, z. B. `mindnet`):
|
|
||||||
|
|
||||||
- `mindnet_notes`
|
|
||||||
- `mindnet_chunks`
|
|
||||||
- `mindnet_edges`
|
|
||||||
|
|
||||||
Die Collections werden über:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m scripts.reset_qdrant --mode wipe --prefix "$COLLECTION_PREFIX"
|
|
||||||
```
|
|
||||||
|
|
||||||
**vollständig neu angelegt**, inkl. Payload-Indizes (Details in 6.1).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2.3 Notes – Payload & Felder
|
|
||||||
|
|
||||||
Minimale, indexierte Felder (Auszug, Schema laut `diag_payload_indexes`):
|
|
||||||
|
|
||||||
- `note_id` (keyword) – stabile Note-ID (Frontmatter `id`)
|
|
||||||
- `title` (text) – Notiz-Titel
|
|
||||||
- `type` (keyword) – logischer Typ (z. B. `concept`, `project`, `profile`, `journal`, `source`)
|
|
||||||
- `tags` (keyword[]) – Tags aus Frontmatter
|
|
||||||
- `updated` (integer) – Zeitstempel (z. B. `YYYYMMDDHHMMSS` oder epoch; Implementierungsdetail)
|
|
||||||
|
|
||||||
Weitere Felder (nicht alle indexiert, aber im Payload vorhanden):
|
|
||||||
|
|
||||||
- `retriever_weight` (float) – wie stark diese Note/Chunks im Retrieval gewichtet werden
|
|
||||||
- `chunk_profile` (string) – Name des verwendeten Chunk-Profils
|
|
||||||
- `edge_defaults` (string[]) – Liste von Default-Relationen pro Typ (z. B. `["references","related_to"]`)
|
|
||||||
- `confidentiality`, `visibility`, weitere Metadaten aus Frontmatter
|
|
||||||
|
|
||||||
Diese Felder werden in `app/core/note_payload.py` aus Frontmatter + `types.yaml` konstruiert.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2.4 Chunks – Payload & Felder
|
|
||||||
|
|
||||||
Indexierte Kernfelder:
|
|
||||||
|
|
||||||
- `note_id` (keyword) – Referenz auf die übergeordnete Note
|
|
||||||
- `chunk_id` (keyword) – deterministische Chunk-ID:
|
|
||||||
`"{note_id}#c{index:02d}"` (z. B. `20251110-ollama-llm-9f0a12#c02`)
|
|
||||||
- `index` (integer) – 0-basiert; Position in der Note
|
|
||||||
- `type` (keyword) – Note-Typ (vom Note geerbt)
|
|
||||||
- `tags` (keyword[]) – Tags (vom Note geerbt)
|
|
||||||
|
|
||||||
Weitere wichtige Payload-Felder:
|
|
||||||
|
|
||||||
- `ord` (integer) – 1-basiertes Pendant zu `index` (für menschliche Lesbarkeit)
|
|
||||||
- `text` (string) – eigentlicher Chunk-Text (ggf. gereinigt/normalisiert)
|
|
||||||
- `window` (string) – Kontext-Fenster (z. B. Chunk ± Nachbarn)
|
|
||||||
- `retriever_weight` (float) – gültiger Wert aus `types.yaml` (oder Default)
|
|
||||||
- `chunk_profile` (string) – verwendetes Profil, z. B. `short`, `medium`, `long`, `by_heading`
|
|
||||||
- `neighbors_prev` (string[]) – Liste von `chunk_id`s direkter Vorgänger (i. d. R. 0 oder 1 ID)
|
|
||||||
- `neighbors_next` (string[]) – Liste von `chunk_id`s direkter Nachfolger
|
|
||||||
|
|
||||||
Die Konstruktion erfolgt in `app/core/chunk_payload.py` auf Basis der Chunks aus `chunker.py` und der aufgelösten Typ-Defaults.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2.5 Edges – Payload & Felder
|
|
||||||
|
|
||||||
Indexierte Felder:
|
|
||||||
|
|
||||||
- `note_id` (keyword) – Note, zu der der **Quell-Chunk** gehört
|
|
||||||
- `source_id` (keyword) – i. d. R. `chunk_id` des Quell-Chunks (z. B. `2025…#c00`)
|
|
||||||
- `target_id` (keyword) – Zielobjekt (z. B.:
|
|
||||||
- `chunk_id` eines anderen Chunks
|
|
||||||
- Note-Titel (`"Embeddings 101"`) bei **konzeptionellen Referenzen**
|
|
||||||
- `kind` (keyword) – Kantenart:
|
|
||||||
- Struktur: `belongs_to`, `next`, `prev`
|
|
||||||
- Explizit: `references`
|
|
||||||
- Inline: z. B. `similar_to`, `depends_on`, `related_to`
|
|
||||||
- Typ-Defaults: ebenfalls z. B. `depends_on`, `related_to` (aus `edge_defaults`)
|
|
||||||
- `scope` (keyword) – aktuell immer `"chunk"` (Kante wird auf Chunk-Ebene geführt)
|
|
||||||
- `chunk_id` (keyword) – `chunk_id` des Quell-Chunks
|
|
||||||
|
|
||||||
Weitere Payload-Felder:
|
|
||||||
|
|
||||||
- `rule_id` (string) – Herkunftsregel:
|
|
||||||
- Struktur:
|
|
||||||
- `structure:belongs_to`
|
|
||||||
- `structure:next`
|
|
||||||
- `structure:prev`
|
|
||||||
- Explizite Wiki-Links:
|
|
||||||
- `explicit:wikilink`
|
|
||||||
- Inline-Relationen:
|
|
||||||
- `inline:rel`
|
|
||||||
- Typ-Defaults aus `types.yaml`:
|
|
||||||
- `edge_defaults:<type>:<relation>`
|
|
||||||
z. B. `edge_defaults:concept:related_to`
|
|
||||||
- `confidence` (float) – Stärke / Vertrauensgrad:
|
|
||||||
- Struktur-Kanten: `1.0`
|
|
||||||
- Explizite Wiki-Links: `1.0`
|
|
||||||
- Inline-Relationen (`[[rel:… …]]`): z. B. `0.95`
|
|
||||||
- Typ-Defaults: z. B. `0.7`
|
|
||||||
|
|
||||||
Edges werden in `app/core/derive_edges.py` erzeugt und in `mindnet_edges` gespeichert.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Typ-Konfiguration (`config/types.yaml`)
|
|
||||||
|
|
||||||
### 3.1 Struktur des Files
|
|
||||||
|
|
||||||
`types.yaml` (vereinfachtes Beispiel):
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
version: 1.0
|
|
||||||
default:
|
|
||||||
retriever_weight: 1.0
|
|
||||||
chunk_profile: default
|
|
||||||
|
|
||||||
types:
|
types:
|
||||||
concept:
|
concept:
|
||||||
chunk_profile: medium
|
chunk_profile: medium
|
||||||
edge_defaults: ["references", "related_to"]
|
edge_defaults: ["references", "related_to"]
|
||||||
retriever_weight: 0.35
|
retriever_weight: 0.60
|
||||||
|
|
||||||
task:
|
### 3.2 Retriever-Config (`config/retriever.yaml`)
|
||||||
chunk_profile: short
|
Steuert das Scoring zur Laufzeit (WP04a).
|
||||||
edge_defaults: ["depends_on", "belongs_to"]
|
* **Inhalt (Beispiel):**
|
||||||
retriever_weight: 0.8
|
|
||||||
|
|
||||||
experience:
|
scoring:
|
||||||
chunk_profile: medium
|
semantic_weight: 1.0
|
||||||
edge_defaults: ["derived_from", "inspired_by"]
|
edge_weight: 0.7
|
||||||
retriever_weight: 0.9
|
centrality_weight: 0.5
|
||||||
|
|
||||||
project:
|
### 3.3 Decision Engine (`config/decision_engine.yaml`)
|
||||||
chunk_profile: long
|
**Neu in WP06:** Steuert den Intent-Router.
|
||||||
edge_defaults: ["references", "depends_on"]
|
* Definiert Strategien (`DECISION`, `EMPATHY`, `CODING`, `FACT`).
|
||||||
retriever_weight: 0.97
|
* Definiert `trigger_keywords` und `inject_types` (Late Binding).
|
||||||
|
* Definiert LLM-Router-Settings (`llm_fallback_enabled`).
|
||||||
|
|
||||||
profile:
|
### 3.4 Prompts (`config/prompts.yaml`)
|
||||||
chunk_profile: long
|
Steuert die LLM-Persönlichkeit und Templates.
|
||||||
edge_defaults: ["references", "depends_on"]
|
* Enthält Templates für alle Strategien (z.B. `decision_template`, `empathy_template`, `technical_template`).
|
||||||
retriever_weight: 0.66
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.2 Typauflösung – Reihenfolge der Prioritäten
|
### 3.5 Environment (`.env`)
|
||||||
|
Erweiterung für LLM-Steuerung:
|
||||||
|
|
||||||
Für eine Note mit `type` und optionalen Frontmatter Feldern `retriever_weight`, `chunk_profile` gilt aktuell:
|
MINDNET_LLM_MODEL=phi3:mini
|
||||||
|
MINDNET_OLLAMA_URL=http://127.0.0.1:11434
|
||||||
1. **Typ-spezifische Defaults** aus `types.yaml`:
|
MINDNET_LLM_TIMEOUT=300.0 # Neu: Erhöht für CPU-Inference Cold-Starts
|
||||||
- `retriever_weight` ← `types.<type>.retriever_weight` (falls vorhanden)
|
MINDNET_DECISION_CONFIG="config/decision_engine.yaml"
|
||||||
- `chunk_profile` ← `types.<type>.chunk_profile` (falls vorhanden)
|
|
||||||
2. **Globaler Default** `default` in `types.yaml`, falls Typ-Eintrag fehlt.
|
|
||||||
3. **Frontmatter `retriever_weight` / `chunk_profile`** werden aktuell *nicht* mehr als Konfigurationsebene verwendet, sondern eher als historische Relikte. (Dies kann zukünftig wieder aktiviert werden, ist aber im aktuellen Stand bewusst abgeschaltet zugunsten klarer, zentraler Konfiguration über `types.yaml`.)
|
|
||||||
|
|
||||||
Das Ergebnis dieser Auflösung wird im Payload als:
|
|
||||||
|
|
||||||
- `note_payload["retriever_weight"]`
|
|
||||||
- `note_payload["chunk_profile"]`
|
|
||||||
|
|
||||||
gesetzt und **1:1 an alle Chunks vererbt**.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 4. Import-Pipeline (Markdown → Qdrant)
|
## 4. Import-Pipeline (Markdown → Qdrant)
|
||||||
|
|
||||||
### 4.1 Runbook
|
Das Skript `scripts/import_markdown.py` orchestriert den Prozess.
|
||||||
|
|
||||||
Standard-Import (mit Purge-Before-Upsert):
|
### 4.1 Verarbeitungsschritte
|
||||||
|
|
||||||
```bash
|
1. **Discovery & Parsing:**
|
||||||
export COLLECTION_PREFIX=mindnet
|
* Einlesen der `.md` Dateien. Hash-Vergleich (Body/Frontmatter) zur Erkennung von Änderungen.
|
||||||
export MINDNET_TYPES_FILE="$(pwd)/config/types.yaml"
|
2. **Typauflösung:**
|
||||||
|
* Laden der `types.yaml`. Bestimmen des effektiven Typs und der `edge_defaults`.
|
||||||
python3 -m scripts.import_markdown \
|
3. **Chunking:**
|
||||||
--vault ./mindnet_v2_test_vault \
|
* Zerlegung via `chunker.py` basierend auf `chunk_profile` (z.B. `by_heading`, `short`, `long`).
|
||||||
--apply \
|
* Trennung von `text` (Kern) und `window` (Embedding-Kontext).
|
||||||
--purge-before-upsert \
|
4. **Kantenableitung (Edge Derivation):**
|
||||||
--prefix "$COLLECTION_PREFIX"
|
Die `derive_edges.py` erzeugt Kanten in strikter Reihenfolge:
|
||||||
```
|
1. **Inline-Edges:** `[[rel:depends_on X]]` → `kind=depends_on`, `rule_id=inline:rel`, `conf=0.95`.
|
||||||
|
2. **Callout-Edges:** `> [!edge] related_to: [[X]]` → `kind=related_to`, `rule_id=callout:edge`, `conf=0.90`.
|
||||||
Nur Sync-Deletes (entfernte Dateien in Qdrant aufräumen):
|
3. **Explizite Referenzen:** `[[X]]` → `kind=references`, `rule_id=explicit:wikilink`, `conf=1.0`.
|
||||||
|
4. **Typ-Defaults:** Für jede Referenz werden Zusatzkanten gemäß `edge_defaults` erzeugt (z.B. `project` -> `depends_on`). `rule_id=edge_defaults:...`, `conf=0.7`.
|
||||||
```bash
|
5. **Struktur:** `belongs_to`, `next`, `prev` (automatisch).
|
||||||
python3 -m scripts.import_markdown \
|
5. **Upsert:**
|
||||||
--vault ./mindnet_v2_test_vault \
|
* Schreiben in Qdrant. Nutzung von `--purge-before-upsert` für saubere Updates.
|
||||||
--sync-deletes \
|
|
||||||
--apply \
|
|
||||||
--prefix "$COLLECTION_PREFIX"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 4.2 Verarbeitungsschritte
|
## 5. Retriever-Architektur & Scoring
|
||||||
|
|
||||||
**1. Discovery & Parsing**
|
Der Retriever (`app/core/retriever.py`) unterstützt zwei Modi. Für den Chat wird **zwingend** der Hybrid-Modus genutzt.
|
||||||
|
|
||||||
- `import_markdown.py` traversiert das Vault‐Verzeichnis.
|
### 5.1 Betriebsmodi
|
||||||
- Für jede `.md`:
|
* **Semantic:** Reine Vektorsuche. Schnell.
|
||||||
- YAML-Frontmatter extrahieren (id, title, type, created, updated, tags, …).
|
* **Hybrid:** Vektorsuche + Graph-Expansion (Tiefe N) + Re-Ranking.
|
||||||
- Body (Markdown) als String.
|
|
||||||
|
|
||||||
**2. Typauflösung & Payload-Bau (Note)**
|
### 5.2 Scoring-Formel (WP04a)
|
||||||
|
Die Relevanzberechnung ist nun eine gewichtete Summe:
|
||||||
|
|
||||||
- Laden & Auflösen von `types.yaml` (über ENV `MINDNET_TYPES_FILE` oder Default `./config/types.yaml`).
|
$$
|
||||||
- Bestimmung des effektiven Typs (`type` aus Frontmatter; ggf. Fallback).
|
TotalScore = (W_{sem} \cdot S_{sem} \cdot \max(W_{type}, 0)) + (W_{edge} \cdot B_{edge}) + (W_{cent} \cdot B_{cent})
|
||||||
- Anwendung der Typdefaults:
|
$$
|
||||||
- `retriever_weight` und `chunk_profile` werden aus `types.yaml` gelesen.
|
|
||||||
- Konstruktion des Note-Payloads via `make_note_payload` (in `note_payload.py`):
|
|
||||||
- Felder wie `note_id`, `title`, `type`, `tags`, `updated`, `retriever_weight`, `chunk_profile`, `edge_defaults`, …
|
|
||||||
|
|
||||||
**3. Chunking**
|
* **Komponenten:**
|
||||||
|
* $S_{sem}$: Semantic Score (Cosine Similarity).
|
||||||
|
* $W_{type}$: `retriever_weight` (aus Note/Chunk Payload).
|
||||||
|
* $B_{edge}$: Edge-Bonus (Summe der Konfidenzen eingehender relevanter Kanten).
|
||||||
|
* $B_{cent}$: Centrality-Bonus (im lokalen Subgraphen).
|
||||||
|
* **Gewichte ($W$):** Stammen aus `retriever.yaml`.
|
||||||
|
|
||||||
- Übergabe des Note-Bodies + `chunk_profile` an `chunker.py`.
|
### 5.3 Explanation Layer (WP04b)
|
||||||
- `chunker.py` nutzt `chunk_config.py`, das definierte Profile bereitstellt, z. B.:
|
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`.
|
||||||
|
|
||||||
```python
|
### 5.4 Graph-Expansion
|
||||||
CHUNK_PROFILES = {
|
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.
|
||||||
"short": {"max_tokens": 128, "overlap": 32},
|
|
||||||
"medium": {"max_tokens": 256, "overlap": 64},
|
|
||||||
"long": {"max_tokens": 512, "overlap": 128},
|
|
||||||
"by_heading": {"strategy": "by_heading", "max_chars": 2000},
|
|
||||||
"default": {"max_tokens": 256, "overlap": 64},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- Ergebnis: Liste geordneter Chunks mit:
|
|
||||||
- `chunk_id` (`note_id#cXX`),
|
|
||||||
- `index` (0..N-1),
|
|
||||||
- `ord` (1..N),
|
|
||||||
- `text`,
|
|
||||||
- `window` (inkl. Nachbartexte),
|
|
||||||
- `neighbors_prev` / `neighbors_next`.
|
|
||||||
|
|
||||||
**4. Chunk-Payloads**
|
|
||||||
|
|
||||||
- In `chunk_payload.py` werden für jeden Chunk die Payloads gebaut:
|
|
||||||
- Vererbung von `note_id`, `type`, `tags`, `retriever_weight`, `chunk_profile`.
|
|
||||||
- Setzen von `index`, `ord`, `neighbors_prev`, `neighbors_next`.
|
|
||||||
- Persistieren von `text` und `window`.
|
|
||||||
|
|
||||||
**5. Kantenableitung (Edges)**
|
|
||||||
|
|
||||||
- `derive_edges.py` wird mit Note + Chunks + Typinformationen aufgerufen.
|
|
||||||
- Es entstehen mehrere Gruppen von Kanten:
|
|
||||||
1. **Struktur-Kanten**:
|
|
||||||
- `belongs_to`: Chunk → Note
|
|
||||||
- `next`: Chunk[i] → Chunk[i+1]
|
|
||||||
- `prev`: Chunk[i] → Chunk[i-1]
|
|
||||||
2. **Explizite Kanten aus Text**:
|
|
||||||
- Wiki-Links: `[[Target Title]]` → `kind="references"`, `rule_id="explicit:wikilink"`, `confidence=1.0`.
|
|
||||||
- Inline-Relationen: `[[rel:depends_on Embeddings 101]]`:
|
|
||||||
- `kind="depends_on"`
|
|
||||||
- `rule_id="inline:rel"`
|
|
||||||
- `confidence≈0.95`
|
|
||||||
- `target_id="Embeddings 101"` (Titel, nicht ID – Auflösung erfolgt später im Agenten).
|
|
||||||
3. **Typ-basierte Defaults (`edge_defaults`)**:
|
|
||||||
- Aus `types.yaml` je `type`: Liste von Relations-Kinds, z. B.:
|
|
||||||
- `concept.edge_defaults = ["references","related_to"]`
|
|
||||||
- `project.edge_defaults = ["references","depends_on"]`
|
|
||||||
- Für jede explizite Referenz Quelle→Ziel (z. B. `references`, `similar_to`) werden **zusätzliche Kanten** erzeugt, z. B.:
|
|
||||||
- `edge_defaults:project:depends_on`
|
|
||||||
- `edge_defaults:concept:related_to`
|
|
||||||
- `confidence≈0.7`.
|
|
||||||
4. **Deduplication**:
|
|
||||||
- Alle Kanten werden in einem Set anhand eines Keys wie
|
|
||||||
- `(kind, scope, source_id, target_id, rule_id)`
|
|
||||||
dedupliziert (idempotent).
|
|
||||||
|
|
||||||
**6. Upsert nach Qdrant**
|
|
||||||
|
|
||||||
- Punkte (Notes, Chunks, Edges) werden via `qdrant_points.py` in die entsprechenden Collections upserted.
|
|
||||||
- Option `--purge-before-upsert` sorgt dafür, dass alte Punkte mit denselben IDs entfernt werden, bevor neue geschrieben werden (stabiler Reimport).
|
|
||||||
- `--sync-deletes` entfernt Punkte, deren zugehörige Dateien im Vault nicht mehr existieren.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 5. Edges im Detail – Semantik & Regeln
|
## 6. RAG & Chat Architektur (WP06 Hybrid Router)
|
||||||
|
|
||||||
### 5.1 Struktur-Kanten
|
Der Flow für eine Chat-Anfrage (`/chat`) wurde in WP06 auf eine **Configuration-Driven Architecture** umgestellt. Der `ChatRouter` (`app/routers/chat.py`) fungiert als zentraler Dispatcher.
|
||||||
|
|
||||||
Erzeugt für **jede Note** mit >0 Chunks:
|
### 6.1 Architektur-Pattern: Intent Router
|
||||||
|
Die Behandlung einer Anfrage ist nicht mehr hartkodiert, sondern wird dynamisch zur Laufzeit entschieden.
|
||||||
|
* **Input:** User Message.
|
||||||
|
* **Config:** `config/decision_engine.yaml` (Strategien & Keywords).
|
||||||
|
* **Komponenten:**
|
||||||
|
* **Fast Path:** Keyword Matching (CPU-schonend).
|
||||||
|
* **Slow Path:** LLM-basierter Semantic Router (für subtile Intents).
|
||||||
|
|
||||||
- **belongs_to**
|
### 6.2 Schritt 1: Intent Detection (Hybrid)
|
||||||
- pro Chunk genau eine Kante:
|
Der Router ermittelt die Absicht (`Intent`) des Nutzers.
|
||||||
- `source_id = chunk_id`
|
1. **Keyword Scan (Fast Path):**
|
||||||
- `target_id = note_id` *oder* (konzeptionell) ein Note-Identifikator
|
* Iteration über alle Strategien in `decision_engine.yaml`.
|
||||||
- `kind = "belongs_to"`
|
* Prüfung auf `trigger_keywords`.
|
||||||
- `scope = "chunk"`
|
* **Best Match:** Bei mehreren Treffern gewinnt das längste/spezifischste Keyword (Robustheit gegen Shadowing).
|
||||||
- `rule_id = "structure:belongs_to"`
|
2. **LLM Fallback (Slow Path):**
|
||||||
- `confidence = 1.0`
|
* Nur aktiv, wenn `llm_fallback_enabled: true`.
|
||||||
- **next / prev**
|
* Greift, wenn keine Keywords gefunden wurden.
|
||||||
- für Index i (`0..N-2`):
|
* Sendet die Query an das LLM mit einem Klassifizierungs-Prompt (`llm_router_prompt`).
|
||||||
- `next`: `chunk_i → chunk_{i+1}`
|
* Ergebnis: `EMPATHY`, `DECISION`, `CODING` oder `FACT` (Default).
|
||||||
- `prev`: `chunk_{i+1} → chunk_i`
|
|
||||||
- `kind = "next"` bzw. `"prev"`
|
|
||||||
- `scope = "chunk"`
|
|
||||||
- `rule_id = "structure:next"` / `"structure:prev"`
|
|
||||||
- `confidence = 1.0`
|
|
||||||
|
|
||||||
Tests (`tests.test_edges_smoke` / `tests.test_edges_all`) stellen sicher:
|
### 6.3 Schritt 2: Strategy Resolution (Late Binding)
|
||||||
|
Basierend auf dem Intent lädt der Router die Parameter:
|
||||||
|
* **inject_types:** Liste der Notiz-Typen, die erzwungen werden sollen (z.B. `["value", "goal"]` bei `DECISION`).
|
||||||
|
* **prompt_template:** Schlüssel für das Template in `prompts.yaml` (z.B. `decision_template`, `empathy_template`).
|
||||||
|
|
||||||
- `belongs_to` == `#chunks`
|
### 6.4 Schritt 3: Multi-Stage Retrieval
|
||||||
- `next` == `prev` == `#chunks - 1`
|
1. **Primary Retrieval:** Hybride Suche nach der User-Query (findet Fakten).
|
||||||
- keine Duplikate der Strukturkanten.
|
2. **Strategic Retrieval (Conditional):** Wenn `inject_types` definiert sind, erfolgt eine zweite Suche, die explizit auf diese Typen filtert.
|
||||||
|
3. **Merge:** Ergebnisse werden dedupliziert zusammengeführt.
|
||||||
|
|
||||||
|
### 6.5 Schritt 4: Generation & Response
|
||||||
|
* **Context Enrichment:** Metadaten (`[VALUE]`, `[GOAL]`, `[SCORE]`) werden in den Context-String injiziert, um dem LLM die Rolle des Textstücks zu signalisieren.
|
||||||
|
* **Templating:** Das LLM erhält den Prompt basierend auf dem gewählten Template.
|
||||||
|
* **Execution:** Der `LLMService` führt den Call aus. Ein konfigurierbarer Timeout (`MINDNET_LLM_TIMEOUT`) fängt Cold-Start-Verzögerungen auf CPU-Hardware ab.
|
||||||
|
* **Response:** Rückgabe enthält Antworttext, Quellenliste und den erkannten `intent` (für Debugging/Frontend).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 5.2 Explizite Wiki-Links (`[[Target Title]]`)
|
## 7. Feedback & Logging Architektur (WP04c)
|
||||||
|
|
||||||
- Parser in `derive_edges.py` sucht im Chunk-Text nach Mustern:
|
Mindnet implementiert ein "Data Flywheel" zur späteren Optimierung (Self-Tuning).
|
||||||
- `[[Some Page]]` (kein `rel:` Präfix)
|
|
||||||
- Erzeugt Kanten:
|
|
||||||
- `kind = "references"`
|
|
||||||
- `scope = "chunk"`
|
|
||||||
- `source_id = chunk_id`
|
|
||||||
- `target_id = "<Titel aus dem Link>"` (z. B. `"Vector DB Basics"`)
|
|
||||||
- `rule_id = "explicit:wikilink"`
|
|
||||||
- `confidence = 1.0`
|
|
||||||
|
|
||||||
Diese Kanten bilden das **explizite Referenznetz** des Nutzers ab (Obsidian-typische Wikilinks).
|
### 7.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
|
||||||
|
1. **`search_history.jsonl`**:
|
||||||
|
* Speichert jede Anfrage an `/query` und `/chat`.
|
||||||
|
* 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?").
|
||||||
|
|
||||||
|
### 7.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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 5.3 Inline-Relationen (`[[rel:… …]]`)
|
## 8. Indizes & Performance
|
||||||
|
|
||||||
Aktuell **implementiert und funktional** ist folgende Form:
|
Damit Qdrant performant bleibt, sind Payload-Indizes essenziell.
|
||||||
|
|
||||||
- **Format (aktuell unterstützt):**
|
**Erforderliche Indizes:**
|
||||||
|
* **Notes:** `note_id`, `type`, `tags`.
|
||||||
|
* **Chunks:** `note_id`, `chunk_id`, `type`.
|
||||||
|
* **Edges:** `source_id`, `target_id`, `kind`, `scope`, `note_id`.
|
||||||
|
|
||||||
```md
|
Validierung erfolgt über `tests/ensure_indexes_and_show.py`.
|
||||||
[[rel:depends_on Embeddings 101]]
|
|
||||||
[[rel:similar_to Vector DB Basics]]
|
|
||||||
[[rel:related_to Qdrant Vektordatenbank]]
|
|
||||||
```
|
|
||||||
|
|
||||||
- Parsing-Strategie:
|
|
||||||
- Link-Inhalt wird gesplittet:
|
|
||||||
- Erster Token: `rel:depends_on`
|
|
||||||
- Rest: Zielbezeichnung (`Embeddings 101`)
|
|
||||||
- `kind` wird aus dem Teil `depends_on` extrahiert (z. B. `similar_to`, `related_to`).
|
|
||||||
- `target_id` wird aus dem Rest (meist ein Titel) abgeleitet.
|
|
||||||
|
|
||||||
- Ergebnis-Kante:
|
|
||||||
- `kind = "<Relation aus rel:…>"`
|
|
||||||
- `scope = "chunk"`
|
|
||||||
- `source_id = chunk_id`
|
|
||||||
- `target_id = "<Ziel-Titel>"`
|
|
||||||
- `rule_id = "inline:rel"`
|
|
||||||
- `confidence ≈ 0.95`
|
|
||||||
|
|
||||||
- **Nicht unterstützt (Stand jetzt):**
|
|
||||||
|
|
||||||
```md
|
|
||||||
rel: depends_on [[Embeddings 101]] [[Vector DB Basics]]
|
|
||||||
```
|
|
||||||
|
|
||||||
Diese Syntax wird derzeit **nicht** erkannt.
|
|
||||||
Multi-Target-Inline-Relationen (`rel: similar_to [[A]] [[B]]`) sind ein **offener Task**.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 5.4 Typ-basierte Default-Edges (`edge_defaults`)
|
## 9. Offene Punkte / Known Limitations
|
||||||
|
|
||||||
Zweck:
|
1. **Multi-Target Inline-Relations:**
|
||||||
|
* `rel: similar_to [[A]] [[B]]` wird aktuell parser-seitig nicht unterstützt.
|
||||||
- Für bestimmte Typen (vor allem `concept`, `project`, `profile`) sollen zusätzliche Kanten automatisch ergänzt werden, um das **Semantiknetz zu verdichten**, ohne dass der Nutzer jede Relation explizit pflegen muss.
|
* Workaround: Zwei separate Inline-Links `[[rel:similar_to A]] [[rel:similar_to B]]`.
|
||||||
|
2. **Unresolved Targets:**
|
||||||
Konfiguration:
|
* Kanten zu Notizen, die noch nicht existieren, werden mit `target_id="Titel"` angelegt.
|
||||||
|
* Heilung durch `scripts/resolve_unresolved_references.py` möglich.
|
||||||
- In `types.yaml` definiert, z. B.:
|
3. **Vektor-Konfiguration für Edges:**
|
||||||
|
* `mindnet_edges` hat aktuell keine Vektoren (`vectors = null`). Eine semantische Suche *auf Kanten* ist noch nicht möglich.
|
||||||
```yaml
|
|
||||||
types:
|
|
||||||
concept:
|
|
||||||
edge_defaults: ["references", "related_to"]
|
|
||||||
project:
|
|
||||||
edge_defaults: ["references", "depends_on"]
|
|
||||||
```
|
|
||||||
|
|
||||||
Aktuelle Implementierung:
|
|
||||||
|
|
||||||
- Für jede **explizite** Referenz (Wiki-Link oder Inline-Relation) von Chunk → Ziel:
|
|
||||||
- `kind="references"` (Wiki) oder die Inline-Relation (`depends_on`, `similar_to`, …)
|
|
||||||
- Auf Basis des Note-Typs (`type`) wird pro Default-Relation eine zusätzliche Kante erzeugt:
|
|
||||||
|
|
||||||
Beispiel:
|
|
||||||
|
|
||||||
- Note-Typ: `project`
|
|
||||||
- `edge_defaults: ["references","depends_on"]`
|
|
||||||
- Explizit: `references` von `Edge Index` → `Embeddings 101`
|
|
||||||
- Abgeleitete Kanten:
|
|
||||||
- `kind="references"`, `rule_id="edge_defaults:project:references"`, `confidence=0.7`
|
|
||||||
- `kind="depends_on"`, `rule_id="edge_defaults:project:depends_on"`, `confidence=0.7`
|
|
||||||
|
|
||||||
- Symmetrische Kanten:
|
|
||||||
- Für einige Relations-Typen (z. B. `related_to`) wird zusätzlich eine **spiegelbildliche** Kante Ziel → Quelle erzeugt.
|
|
||||||
- Dies erklärt in Tests z. B. Paare wie:
|
|
||||||
- `related_to (Source=Ollama LLM, Target=Qdrant Vektordatenbank)`
|
|
||||||
- `related_to (Source=Qdrant Vektordatenbank, Target=Ollama LLM)`
|
|
||||||
|
|
||||||
- Deduplication:
|
|
||||||
- Es wird verhindert, dass mehrfach identische Kanten geschrieben werden.
|
|
||||||
- Schlüssel: `(kind, scope, source_id, target_id, rule_id)`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5.5 `rule_id` & `confidence` – Bedeutung
|
|
||||||
|
|
||||||
**`rule_id`** kodiert **Herkunft** und **Regel**, z. B.:
|
|
||||||
|
|
||||||
- `structure:belongs_to`, `structure:next`, `structure:prev`
|
|
||||||
- `explicit:wikilink`
|
|
||||||
- `inline:rel`
|
|
||||||
- `edge_defaults:<type>:<relation>`
|
|
||||||
|
|
||||||
**`confidence`** dient als späterer Gewichtungsfaktor im Retrieval / Ranking:
|
|
||||||
|
|
||||||
- `1.0` → harte Struktur- oder explizite Kante (vom Nutzer direkt gesetzt)
|
|
||||||
- `0.95` → Inline-Relation (stark, aber nicht so „hart“ wie die reine Referenz)
|
|
||||||
- `0.7` → Typ-Default-Edges (abgeleitete Hypothesen aus Typwissen)
|
|
||||||
|
|
||||||
Ein künftiger LLM-Agent kann daraus z. B.:
|
|
||||||
|
|
||||||
- Kanten mit hoher `confidence` priorisieren,
|
|
||||||
- Default-Edges als schwächere Hinweise betrachten,
|
|
||||||
- Inline-Relationen gezielt als semantische Aussagen über die Beziehung interpretieren.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Qdrant-Schema & Indizes
|
|
||||||
|
|
||||||
### 6.1 Erstellung & Indizes
|
|
||||||
|
|
||||||
Die Erstellung erfolgt über:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m scripts.reset_qdrant --mode wipe --prefix "$COLLECTION_PREFIX"
|
|
||||||
```
|
|
||||||
|
|
||||||
Intern:
|
|
||||||
|
|
||||||
- `qdrant.py` / `setup_mindnet_collections.py`:
|
|
||||||
- Collections anlegen, ggf. mit Vektor-Konfiguration (Single-Vector; Named-Vectors sind vorbereitet aber optional).
|
|
||||||
- `ensure_payload_indexes()`:
|
|
||||||
- Legt für jede Collection die relevanten Payload-Indizes an.
|
|
||||||
|
|
||||||
Verifizierbar durch:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 -m tests.ensure_indexes_and_show
|
|
||||||
```
|
|
||||||
|
|
||||||
Beispielauszug (bereits real so gesehen):
|
|
||||||
|
|
||||||
- **mindnet_notes**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"tags": { "data_type": "keyword", "points": 8 },
|
|
||||||
"note_id":{ "data_type": "keyword", "points": 8 },
|
|
||||||
"title": { "data_type": "text", "points": 8 },
|
|
||||||
"updated":{ "data_type": "integer", "points": 0 },
|
|
||||||
"type": { "data_type": "keyword", "points": 8 }
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- **mindnet_chunks**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"note_id": { "data_type": "keyword", "points": 44 },
|
|
||||||
"chunk_id":{ "data_type": "keyword", "points": 44 },
|
|
||||||
"index": { "data_type": "integer", "points": 44 },
|
|
||||||
"type": { "data_type": "keyword", "points": 44 },
|
|
||||||
"tags": { "data_type": "keyword", "points": 44 }
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- **mindnet_edges**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"scope": { "data_type": "keyword", "points": 135 },
|
|
||||||
"kind": { "data_type": "keyword", "points": 135 },
|
|
||||||
"chunk_id":{ "data_type": "keyword", "points": 135 },
|
|
||||||
"target_id":{ "data_type": "keyword", "points": 135 },
|
|
||||||
"note_id": { "data_type": "keyword", "points": 135 },
|
|
||||||
"source_id":{ "data_type": "keyword", "points": 135 }
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6.2 Schema-Validierung
|
|
||||||
|
|
||||||
`tests/assert_payload_schema.py` prüft:
|
|
||||||
|
|
||||||
- ob die Minimalfelder (`note_id`, `type`, `title`, `updated`, `tags` etc.) vorhanden sind,
|
|
||||||
- berichtet fehlende Felder.
|
|
||||||
|
|
||||||
Nach Korrektur der Indexanlage sollte:
|
|
||||||
|
|
||||||
- `ok = true` sein, bzw. zumindest alle Kernfelder unter `present` geführt werden.
|
|
||||||
(Im aktuellen Stand werden sie als Indizes geführt; Qdrant speichert zusätzliche Felder ohne explizite Schema-Zeile, was technisch unproblematisch ist.)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Nutzung im Retrieval (Ausblick)
|
|
||||||
|
|
||||||
### 7.1 Typbewusstes Chunk-Retrieval
|
|
||||||
|
|
||||||
Ein typischer Query-Pfad eines LLM-Agents:
|
|
||||||
|
|
||||||
1. Query → Embedding
|
|
||||||
2. Suche in `mindnet_chunks` mit Filter, z. B.:
|
|
||||||
|
|
||||||
```python
|
|
||||||
f = rest.Filter(
|
|
||||||
must=[
|
|
||||||
rest.FieldCondition(key="type", match=rest.MatchValue(value="concept")),
|
|
||||||
rest.FieldCondition(key="tags", match=rest.MatchAny(any=["ki","ollama"]))
|
|
||||||
]
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Treffer werden nach:
|
|
||||||
- Vektor-Score,
|
|
||||||
- `retriever_weight`,
|
|
||||||
- ggf. Edges (z. B. Projekte mit `depends_on` → Konzepte) gewichtet.
|
|
||||||
|
|
||||||
### 7.2 Graph-orientierte Navigation
|
|
||||||
|
|
||||||
Basierend auf `mindnet_edges` kann der Agent:
|
|
||||||
|
|
||||||
- ausgehend von einem relevanten Chunk:
|
|
||||||
- Struktur-Kanten (`next`, `prev`) zur Kontextvergrößerung nutzen,
|
|
||||||
- `references` / `depends_on` / `related_to` interpretieren,
|
|
||||||
- `edge_defaults` als semantische Ausdehnung (z. B. von `project` zu seinen `concept`-Bausteinen) nutzen.
|
|
||||||
|
|
||||||
Die Bedeutung der Kanten ist dabei durch `rule_id` und `confidence` klar nachvollziehbar.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. Offene Punkte / Known Limitations
|
|
||||||
|
|
||||||
1. **Multi-Target Inline-Relationen**
|
|
||||||
Syntax wie:
|
|
||||||
|
|
||||||
```md
|
|
||||||
[[rel:similar_to Vector DB Basics]] [[rel:similar_to Embeddings 101]]
|
|
||||||
```
|
|
||||||
funktioniert (zwei separate Inline-Links).
|
|
||||||
**Nicht** unterstützt (Stand jetzt):
|
|
||||||
|
|
||||||
```md
|
|
||||||
[[rel:similar_to Vector DB Basics]] [[Embeddings 101]]
|
|
||||||
rel: similar_to [[Vector DB Basics]] [[Embeddings 101]]
|
|
||||||
```
|
|
||||||
|
|
||||||
→ Offener Task: Parser erweitern, um mehrere Ziele in einer Inline-Relation zu unterstützen.
|
|
||||||
|
|
||||||
2. **Callout-Edges (`[!edge]`)**
|
|
||||||
- Konzeptionell vorgesehen, z. B.:
|
|
||||||
|
|
||||||
```md
|
|
||||||
> [!edge] related_to: [[Vector DB Basics]]
|
|
||||||
```
|
|
||||||
|
|
||||||
- Im aktuellen Implementierungsstand werden Callouts entweder:
|
|
||||||
- gar nicht, oder
|
|
||||||
- nur teilweise verarbeitet (in den aktuellen Test-Runs war `callout_total = 0`).
|
|
||||||
→ Offener Task: Callout-Parser robust implementieren und mit Tests absichern.
|
|
||||||
|
|
||||||
3. **Frontmatter-Overrides für `retriever_weight` / `chunk_profile`**
|
|
||||||
- Aktuell **nicht** wirksam.
|
|
||||||
- Typdefaults aus `types.yaml` sind der **Single Source of Truth**.
|
|
||||||
- Später können kontrollierte Overrides (z. B. für Sonderfälle) eingeführt werden.
|
|
||||||
|
|
||||||
4. **Vektor-Konfiguration für Edges**
|
|
||||||
- `mindnet_edges` wird derzeit ohne Vektoren betrieben (`vectors = null`).
|
|
||||||
- Später könnte z. B. eine semantische Repräsentation von Kanten eingeführt werden (z. B. Embedding von `(source_chunk_text + relation + target_title)`).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. Zusammenfassung
|
|
||||||
|
|
||||||
- Die Mindnet-V2-Architektur implementiert einen **dreistufigen Speicher**:
|
|
||||||
- Notes (`mindnet_notes`),
|
|
||||||
- Chunks (`mindnet_chunks`),
|
|
||||||
- Edges (`mindnet_edges`).
|
|
||||||
|
|
||||||
- **`types.yaml`** steuert:
|
|
||||||
- `retriever_weight` und `chunk_profile` je Typ (inkl. Default),
|
|
||||||
- `edge_defaults` je Typ (automatische Relations-Ableitung).
|
|
||||||
|
|
||||||
- Das **Chunking** ist profilbasiert (short/medium/long/by_heading) und deterministisch.
|
|
||||||
|
|
||||||
- Die **Kantenableitung** in `derive_edges.py` erzeugt:
|
|
||||||
- strukturelle Kanten (belongs_to / next / prev),
|
|
||||||
- explizite Kanten aus Wiki-Links (`[[Target]]`),
|
|
||||||
- semantische Inline-Relationen (`[[rel:depends_on Target]]`),
|
|
||||||
- typbasierte Default-Kanten (z. B. `edge_defaults:project:depends_on`).
|
|
||||||
|
|
||||||
- `rule_id` und `confidence` machen die Herkunft jeder Kante transparent und ermöglichen später eine **gewichtete Auswertung** durch LLM-basierte Agenten.
|
|
||||||
|
|
||||||
- Qdrant-Collections und Payload-Indizes sind konsistent eingerichtet und durch Tests verifiziert.
|
|
||||||
|
|
||||||
Dieses Dokument bildet damit das aktuelle technische Gesamtbild von Mindnet V2 ab, inkl. aller relevanten Mechanismen rund um Typen, Chunking, Edges und Qdrant-Schema.
|
|
||||||
|
|
||||||
@@ -0,0 +1,223 @@
|
|||||||
|
# mindnet v2.2 – Pipeline Playbook
|
||||||
|
**Datei:** `docs/mindnet_pipeline_playbook_v2.2.md`
|
||||||
|
**Stand:** 2025-12-09
|
||||||
|
**Status:** **FINAL** (Inkl. WP06 Decision Engine)
|
||||||
|
**Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `mindnet_admin_guide_v2.2.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
<details>
|
||||||
|
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
|
||||||
|
|
||||||
|
- [mindnet v2.2 – Pipeline Playbook](#mindnet-v22--pipeline-playbook)
|
||||||
|
- [](#)
|
||||||
|
- [1. Zweck \& Einordnung](#1-zweck--einordnung)
|
||||||
|
- [2. Die Import-Pipeline (Runbook)](#2-die-import-pipeline-runbook)
|
||||||
|
- [2.1 Der 12-Schritte-Prozess](#21-der-12-schritte-prozess)
|
||||||
|
- [2.2 Standard-Betrieb (Inkrementell)](#22-standard-betrieb-inkrementell)
|
||||||
|
- [2.3 Deployment \& Restart (Systemd)](#23-deployment--restart-systemd)
|
||||||
|
- [2.4 Full Rebuild (Clean Slate)](#24-full-rebuild-clean-slate)
|
||||||
|
- [3. Chunking \& Payload-Aufbau](#3-chunking--payload-aufbau)
|
||||||
|
- [3.1 Chunk-Profile](#31-chunk-profile)
|
||||||
|
- [3.2 Payload-Felder](#32-payload-felder)
|
||||||
|
- [4. Edge-Erzeugung (Die V2-Logik)](#4-edge-erzeugung-die-v2-logik)
|
||||||
|
- [4.1 Prioritäten \& Provenance](#41-prioritäten--provenance)
|
||||||
|
- [4.2 Typ-Defaults](#42-typ-defaults)
|
||||||
|
- [5. Retriever, Chat \& Generation (RAG Pipeline)](#5-retriever-chat--generation-rag-pipeline)
|
||||||
|
- [5.1 Retrieval (Hybrid)](#51-retrieval-hybrid)
|
||||||
|
- [5.2 Intent Router (WP06)](#52-intent-router-wp06)
|
||||||
|
- [5.3 Context Enrichment](#53-context-enrichment)
|
||||||
|
- [5.4 Generation (LLM)](#54-generation-llm)
|
||||||
|
- [6. Feedback \& Lernen (WP04c)](#6-feedback--lernen-wp04c)
|
||||||
|
- [7. Quality Gates \& Tests](#7-quality-gates--tests)
|
||||||
|
- [7.1 Pflicht-Tests vor Commit](#71-pflicht-tests-vor-commit)
|
||||||
|
- [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)
|
||||||
|
|
||||||
|
</details>
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Zweck & Einordnung
|
||||||
|
|
||||||
|
Dieses Playbook ist das zentrale operative Handbuch für die **mindnet-Pipeline**. Es beschreibt, wie Daten vom Markdown-Vault in den Wissensgraphen (Qdrant) gelangen, wie der Retriever betrieben wird und wie die **RAG-Generierung** (inkl. Decision Engine) funktioniert.
|
||||||
|
|
||||||
|
**Zielgruppe:** Dev/Ops, Tech-Leads.
|
||||||
|
**Scope:**
|
||||||
|
* **Ist-Stand (WP01–WP06):** Import, Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat (Hybrid Router), Feedback Loop.
|
||||||
|
* **Roadmap (Ausblick):** Technische Skizze für Self-Tuning (WP08).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Die Import-Pipeline (Runbook)
|
||||||
|
|
||||||
|
Der Import ist der kritischste Prozess ("Data Ingestion"). Er muss **deterministisch** und **idempotent** sein. Wir nutzen `scripts/import_markdown.py` als zentralen Entrypoint.
|
||||||
|
|
||||||
|
### 2.1 Der 12-Schritte-Prozess
|
||||||
|
Gemäß WP03-Spezifikation läuft der Import intern wie folgt ab:
|
||||||
|
|
||||||
|
1. **Markdown lesen:** Rekursives Scannen des Vaults.
|
||||||
|
2. **Frontmatter extrahieren:** Validierung von Pflichtfeldern (`id`, `type`, `title`).
|
||||||
|
3. **Typauflösung:** Bestimmung des `type` via `types.yaml` (Prio: Frontmatter > Pfad > Default).
|
||||||
|
4. **Note-Payload generieren:** Erstellen des JSON-Objekts für `mindnet_notes`.
|
||||||
|
5. **Chunking anwenden:** Zerlegung des Textes basierend auf dem `chunk_profile` des Typs.
|
||||||
|
6. **Inline-Kanten finden:** Parsing von `[[rel:...]]` im Fließtext.
|
||||||
|
7. **Callout-Kanten finden:** Parsing von `> [!edge]` Blöcken.
|
||||||
|
8. **Default-Edges erzeugen:** Anwendung der `edge_defaults` aus der Typ-Registry.
|
||||||
|
9. **Strukturkanten erzeugen:** `belongs_to` (Chunk->Note), `next`/`prev` (Sequenz).
|
||||||
|
10. **Chunks upserten:** Schreiben in Qdrant (`mindnet_chunks`).
|
||||||
|
11. **Edges upserten:** Schreiben in Qdrant (`mindnet_edges`).
|
||||||
|
12. **Diagnose:** Automatischer Check der Integrität nach dem Lauf.
|
||||||
|
|
||||||
|
### 2.2 Standard-Betrieb (Inkrementell)
|
||||||
|
Für regelmäßige Updates (z.B. Cronjob). Erkennt Änderungen via Hash.
|
||||||
|
|
||||||
|
export QDRANT_URL="http://localhost:6333"
|
||||||
|
export COLLECTION_PREFIX="mindnet"
|
||||||
|
|
||||||
|
# Import starten (Apply = Schreiben, Purge = Sauberer Upsert)
|
||||||
|
# Nutzt das Venv der Produktionsumgebung
|
||||||
|
/home/llmadmin/mindnet/.venv/bin/python3 -m scripts.import_markdown \
|
||||||
|
--vault ./vault \
|
||||||
|
--prefix "$COLLECTION_PREFIX" \
|
||||||
|
--apply \
|
||||||
|
--purge-before-upsert \
|
||||||
|
--sync-deletes
|
||||||
|
|
||||||
|
* `--apply`: Ohne dieses Flag läuft ein Dry-Run (nur Simulation).
|
||||||
|
* `--purge-before-upsert`: Löscht vor dem Schreiben einer Note ihre alten Chunks/Edges. Essentiell, um "Geister-Chunks" zu vermeiden, wenn Text gekürzt wurde.
|
||||||
|
* `--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.
|
||||||
|
|
||||||
|
# Neustart des Produktions-Services
|
||||||
|
sudo systemctl restart mindnet-prod
|
||||||
|
|
||||||
|
# Prüfung
|
||||||
|
sudo systemctl status mindnet-prod
|
||||||
|
|
||||||
|
### 2.4 Full Rebuild (Clean Slate)
|
||||||
|
Notwendig bei Änderungen an `types.yaml` (z.B. neue Chunk-Größen) oder Embedding-Modellen.
|
||||||
|
|
||||||
|
# 1. Qdrant Collections löschen und neu anlegen (Wipe inkl. Schema)
|
||||||
|
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
|
||||||
|
|
||||||
|
# 2. Vollständiger Import aller Dateien
|
||||||
|
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Chunking & Payload-Aufbau
|
||||||
|
|
||||||
|
Das Chunking ist profilbasiert und typgesteuert.
|
||||||
|
|
||||||
|
### 3.1 Chunk-Profile
|
||||||
|
In `types.yaml` definiert. Standard-Profile (in `chunk_config.py` implementiert):
|
||||||
|
* `short`: Max 128 Tokens (z.B. für Logs, Chats).
|
||||||
|
* `medium`: Max 256 Tokens (z.B. für Konzepte).
|
||||||
|
* `long`: Max 512 Tokens (z.B. für Essays, Projekte).
|
||||||
|
* `by_heading`: Trennt strikt an Überschriften.
|
||||||
|
|
||||||
|
### 3.2 Payload-Felder
|
||||||
|
Jeder Chunk erhält zwei Text-Felder:
|
||||||
|
* `text`: Der reine Inhalt des Chunks (ohne Overlap). Wird dem Nutzer angezeigt.
|
||||||
|
* `window`: Der Inhalt plus Overlap zu Vorgänger/Nachfolger. Wird für das Embedding genutzt (besserer Kontext).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Edge-Erzeugung (Die V2-Logik)
|
||||||
|
|
||||||
|
In v2.2 entstehen Kanten nach strenger Priorität.
|
||||||
|
|
||||||
|
### 4.1 Prioritäten & Provenance
|
||||||
|
Der Importer setzt `provenance`, `rule_id` und `confidence` automatisch:
|
||||||
|
|
||||||
|
| Priorität | Quelle | Syntax (Bsp.) | Rule ID | Confidence |
|
||||||
|
| :--- | :--- | :--- | :--- | :--- |
|
||||||
|
| **1** | Inline | `[[rel:depends_on X]]` | `inline:rel` | ~0.95 |
|
||||||
|
| **2** | Callout | `> [!edge] related_to: [[X]]` | `callout:edge` | ~0.90 |
|
||||||
|
| **3** | Wikilink | `[[X]]` | `explicit:wikilink` | 1.00 |
|
||||||
|
| **4** | Default | *(via types.yaml)* | `edge_defaults:...` | ~0.70 |
|
||||||
|
| **5** | Struktur | *(automatisch)* | `structure:...` | 1.00 |
|
||||||
|
|
||||||
|
### 4.2 Typ-Defaults
|
||||||
|
Wenn in `types.yaml` für einen Typ `edge_defaults` definiert sind, werden diese **additiv** zu expliziten Links erzeugt.
|
||||||
|
* *Beispiel:* Note Typ `project` verlinkt `[[Tool A]]`.
|
||||||
|
* *Ergebnis:* Kante `references` (explizit) UND Kante `depends_on` (Default).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Retriever, Chat & Generation (RAG Pipeline)
|
||||||
|
|
||||||
|
Der Datenfluss endet nicht beim Finden. Er geht weiter bis zur Antwort.
|
||||||
|
|
||||||
|
### 5.1 Retrieval (Hybrid)
|
||||||
|
Der `/chat` Endpunkt nutzt **Hybrid Retrieval** (Semantic + Graph), um auch logisch verbundene, aber textlich unterschiedliche Notizen zu finden (z.B. Decisions zu einem Projekt).
|
||||||
|
|
||||||
|
### 5.2 Intent Router (WP06)
|
||||||
|
Der Request durchläuft den **Hybrid Router**:
|
||||||
|
1. **Fast Path:** Prüfung auf `trigger_keywords` aus `decision_engine.yaml`.
|
||||||
|
2. **Slow Path:** Falls kein Keyword matched und `llm_fallback_enabled=true`, klassifiziert das LLM den Intent (`DECISION`, `EMPATHY`, `FACT`, `CODING`).
|
||||||
|
3. **Result:** Auswahl der Strategie und der `inject_types` (z.B. Values & Goals).
|
||||||
|
|
||||||
|
### 5.3 Context Enrichment
|
||||||
|
Der Router (`chat.py`) reichert die gefundenen Chunks mit Metadaten an:
|
||||||
|
* **Typ-Injection:** `[DECISION]`, `[PROJECT]`.
|
||||||
|
* **Reasoning-Infos:** `(Score: 0.75)`.
|
||||||
|
* **Zweck:** Ermöglicht kleinen Modellen (Phi-3) das Erkennen von logischen Rollen ("Warum?" vs "Was?").
|
||||||
|
|
||||||
|
### 5.4 Generation (LLM)
|
||||||
|
* **Engine:** Ollama (lokal).
|
||||||
|
* **Modell:** `phi3:mini` (Standard).
|
||||||
|
* **Prompting:** Template wird basierend auf Intent gewählt (`decision_template` vs `empathy_template`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Feedback & Lernen (WP04c)
|
||||||
|
|
||||||
|
Das System schreibt kontinuierlich Logs ("Data Flywheel"):
|
||||||
|
* `data/logs/search_history.jsonl`: Trainingsdaten (Query + Ergebnisse + Breakdown).
|
||||||
|
* `data/logs/feedback.jsonl`: Labels (User-Rating zur `query_id`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Quality Gates & Tests
|
||||||
|
|
||||||
|
Diese Tests garantieren die Stabilität der Pipeline.
|
||||||
|
|
||||||
|
### 7.1 Pflicht-Tests vor Commit
|
||||||
|
|
||||||
|
1. **Payload Dryrun (Schema-Check):**
|
||||||
|
Simuliert Import, prüft JSON-Schema Konformität.
|
||||||
|
|
||||||
|
python3 -m scripts.payload_dryrun --vault ./test_vault
|
||||||
|
|
||||||
|
2. **Full Edge Check (Graph-Integrität):**
|
||||||
|
Prüft Invarianten (z.B. `next` muss reziprok zu `prev` sein).
|
||||||
|
|
||||||
|
python3 -m scripts.edges_full_check
|
||||||
|
|
||||||
|
### 7.2 Smoke-Test (E2E)
|
||||||
|
Prüft am laufenden System (Prod oder Dev), ob Semantik, Graph und Feedback funktionieren.
|
||||||
|
|
||||||
|
# Retriever Test
|
||||||
|
python scripts/test_retriever_smoke.py --mode hybrid --top-k 5
|
||||||
|
|
||||||
|
# Chat / Decision Engine Test (Neu WP06)
|
||||||
|
python tests/test_wp06_decision.py -p 8002 -e EMPATHY -q "Alles ist grau"
|
||||||
|
|
||||||
|
# Feedback Test
|
||||||
|
python tests/test_feedback_smoke.py --url http://localhost:8001/query
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Ausblick & Roadmap (Technische Skizzen)
|
||||||
|
|
||||||
|
Wie entwickeln wir die Pipeline weiter?
|
||||||
|
|
||||||
|
### 8.1 WP-08: Self-Tuning (Skizze)
|
||||||
|
**Ziel:** Die Gewichte in `retriever.yaml` basierend auf `feedback.jsonl` optimieren.
|
||||||
|
**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`.
|
||||||
@@ -0,0 +1,108 @@
|
|||||||
|
# Mindnet v2.2 – User Guide
|
||||||
|
**Datei:** `docs/mindnet_user_guide_v2.2.md`
|
||||||
|
**Stand:** 2025-12-09
|
||||||
|
**Status:** **FINAL** (Inkl. RAG & Multi-Personality Chat)
|
||||||
|
**Quellen:** `knowledge_design.md`, `wp04_retriever_scoring.md`, `Programmplan_V2.2.md`, `Handbuch.md`.
|
||||||
|
|
||||||
|
> **Willkommen bei Mindnet.**
|
||||||
|
> Dies ist dein persönliches Wissensnetzwerk und dein Digitaler Zwilling. Es hilft dir beim Erinnern, beim Entscheiden und beim Reflektieren.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Was Mindnet für dich tut
|
||||||
|
|
||||||
|
Mindnet ist ein **assoziatives Gedächtnis** mit Persönlichkeit. Es unterscheidet sich von einer reinen Suche (wie Google) dadurch, dass es **kontextsensitiv** agiert.
|
||||||
|
|
||||||
|
### 1.1 Das Gedächtnis (Der Graph)
|
||||||
|
Wenn du nach "Projekt Alpha" suchst, findet Mindnet nicht nur das Dokument. Es findet auch:
|
||||||
|
* **Abhängigkeiten:** "Technologie X wird benötigt".
|
||||||
|
* **Entscheidungen:** "Warum nutzen wir X?".
|
||||||
|
* **Ä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:
|
||||||
|
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).
|
||||||
|
4. **Der Coder (CODING):** Liefert technische Schnipsel ohne Smalltalk.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 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")
|
||||||
|
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".
|
||||||
|
* **Was passiert:** Mindnet lädt deine **Werte** (`type: value`) und **Ziele** (`type: goal`) in den Kontext und prüft die Fakten dagegen.
|
||||||
|
* **Beispiel-Dialog:**
|
||||||
|
* *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")
|
||||||
|
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)
|
||||||
|
* **Auslöser:** Alles andere. "Was ist Qdrant?", "Zusammenfassung von X".
|
||||||
|
* **Was passiert:** Standard-Suche nach Wissen ohne spezielle Filter.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 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:
|
||||||
|
* *"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.
|
||||||
|
|
||||||
|
### 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.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).
|
||||||
+35
-10
@@ -1,10 +1,35 @@
|
|||||||
fastapi
|
# --- API Server ---
|
||||||
uvicorn[standard]
|
fastapi>=0.116.1
|
||||||
qdrant-client
|
uvicorn[standard]>=0.35.0
|
||||||
pydantic>=2
|
# httpx wird oft für Tests benötigt
|
||||||
sentence-transformers
|
httpx>=0.28.1
|
||||||
torch
|
|
||||||
python-frontmatter
|
# --- Datenbank ---
|
||||||
tqdm
|
qdrant-client>=1.15.1
|
||||||
requests
|
|
||||||
numpy
|
# --- Datenmodelle & Validierung ---
|
||||||
|
pydantic>=2.11.7
|
||||||
|
numpy>=2.3.2
|
||||||
|
|
||||||
|
# --- Markdown & Parsing (Hier fehlten Pakete!) ---
|
||||||
|
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
|
||||||
@@ -0,0 +1,44 @@
|
|||||||
|
import requests
|
||||||
|
import json
|
||||||
|
import sys
|
||||||
|
|
||||||
|
# Konfiguration
|
||||||
|
API_URL = "http://localhost:8002/chat/" # Port ggf. anpassen
|
||||||
|
QUESTION = "Warum nutzen wir Qdrant für mindnet?" # Eine Frage, zu der du Notizen hast
|
||||||
|
|
||||||
|
def test_chat():
|
||||||
|
payload = {
|
||||||
|
"message": QUESTION,
|
||||||
|
"top_k": 3,
|
||||||
|
"explain": True
|
||||||
|
}
|
||||||
|
|
||||||
|
print(f"Sending Question: '{QUESTION}'...")
|
||||||
|
|
||||||
|
try:
|
||||||
|
response = requests.post(API_URL, json=payload)
|
||||||
|
response.raise_for_status()
|
||||||
|
|
||||||
|
data = response.json()
|
||||||
|
|
||||||
|
print("\n=== RESPONSE ===")
|
||||||
|
print(data["answer"])
|
||||||
|
print("================\n")
|
||||||
|
|
||||||
|
print(f"Query ID: {data['query_id']}")
|
||||||
|
print(f"Latency: {data['latency_ms']}ms")
|
||||||
|
print("\nUsed Sources:")
|
||||||
|
for source in data["sources"]:
|
||||||
|
score = source.get("total_score", 0)
|
||||||
|
note = source.get("note_id", "unknown")
|
||||||
|
print(f"- {note} (Score: {score:.3f})")
|
||||||
|
|
||||||
|
except requests.exceptions.ConnectionError:
|
||||||
|
print("Error: Could not connect to API. Is it running on port 8002?")
|
||||||
|
except Exception as e:
|
||||||
|
print(f"Error: {e}")
|
||||||
|
if 'response' in locals():
|
||||||
|
print(response.text)
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
test_chat()
|
||||||
@@ -0,0 +1,67 @@
|
|||||||
|
import argparse
|
||||||
|
import requests
|
||||||
|
import json
|
||||||
|
import sys
|
||||||
|
|
||||||
|
def main():
|
||||||
|
parser = argparse.ArgumentParser(description="Testet die Explanation-Funktion des Retrievers.")
|
||||||
|
parser.add_argument("--url", default="http://localhost:8002/query", help="URL zum Query Endpoint")
|
||||||
|
parser.add_argument("--query", default="mindnet", help="Suchbegriff")
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
payload = {
|
||||||
|
"mode": "hybrid",
|
||||||
|
"query": args.query,
|
||||||
|
"top_k": 1,
|
||||||
|
"explain": True, # Das neue Flag aus WP-04b
|
||||||
|
"expand": {
|
||||||
|
"depth": 1,
|
||||||
|
"edge_types": ["references", "belongs_to", "depends_on", "related_to"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
print(f"--- Sende Request an {args.url} ---")
|
||||||
|
try:
|
||||||
|
r = requests.post(args.url, json=payload)
|
||||||
|
r.raise_for_status()
|
||||||
|
data = r.json()
|
||||||
|
except Exception as e:
|
||||||
|
print(f"FEHLER: {e}")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
hits = data.get("results", [])
|
||||||
|
if not hits:
|
||||||
|
print("Keine Treffer gefunden.")
|
||||||
|
return
|
||||||
|
|
||||||
|
top_hit = hits[0]
|
||||||
|
print(f"\nTop Treffer: {top_hit.get('node_id')}")
|
||||||
|
print(f"Total Score: {top_hit.get('total_score'):.4f}")
|
||||||
|
|
||||||
|
# Explanation prüfen
|
||||||
|
expl = top_hit.get("explanation")
|
||||||
|
if not expl:
|
||||||
|
print("\n[FAIL] Keine 'explanation' im Response erhalten!")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
print("\n--- EXPLANATION LAYER ---")
|
||||||
|
|
||||||
|
bd = expl.get("breakdown", {})
|
||||||
|
print(f"Breakdown:")
|
||||||
|
print(f" Semantic Contribution: {bd.get('semantic_contribution', 0):.4f}")
|
||||||
|
print(f" Edge Contribution: {bd.get('edge_contribution', 0):.4f}")
|
||||||
|
print(f" Centrality Contribution: {bd.get('centrality_contribution', 0):.4f}")
|
||||||
|
print(f" Typ-Gewicht: {bd.get('node_weight', 0):.2f}")
|
||||||
|
|
||||||
|
print("\nReasons:")
|
||||||
|
for reason in expl.get("reasons", []):
|
||||||
|
kind = reason.get("kind", "").upper()
|
||||||
|
msg = reason.get("message", "")
|
||||||
|
impact = reason.get("score_impact")
|
||||||
|
impact_str = f" ({impact:+.4f})" if impact is not None else ""
|
||||||
|
print(f" [{kind}] {msg}{impact_str}")
|
||||||
|
|
||||||
|
print("\n[SUCCESS] Explanation Layer antwortet korrekt.")
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
@@ -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()
|
||||||
@@ -0,0 +1,122 @@
|
|||||||
|
"""
|
||||||
|
tests/test_wp06_decision.py — Flexibler Integrationstest für WP-06
|
||||||
|
Update:
|
||||||
|
- Timeout 300s.
|
||||||
|
- Zeigt Intent Source an.
|
||||||
|
- Payload/Source Fallback für Metadaten.
|
||||||
|
- Debug-Dump bei unknown Type.
|
||||||
|
"""
|
||||||
|
import requests
|
||||||
|
import json
|
||||||
|
import sys
|
||||||
|
import argparse
|
||||||
|
|
||||||
|
def test_decision_engine(query: str, port: int, expected_intent: str):
|
||||||
|
api_url = f"http://localhost:{port}"
|
||||||
|
print(f"🔵 Starte WP-06 Decision Engine Test gegen {api_url}...\n")
|
||||||
|
|
||||||
|
payload = {
|
||||||
|
"message": query,
|
||||||
|
"top_k": 3,
|
||||||
|
"explain": True
|
||||||
|
}
|
||||||
|
|
||||||
|
try:
|
||||||
|
# Request senden
|
||||||
|
print(f"FRAGE: '{query}'")
|
||||||
|
print("... warte auf LLM (kann auf CPU >120s dauern) ...")
|
||||||
|
|
||||||
|
# FIX: Timeout auf 300 erhöht
|
||||||
|
response = requests.post(f"{api_url}/chat/", json=payload, timeout=300)
|
||||||
|
response.raise_for_status()
|
||||||
|
data = response.json()
|
||||||
|
|
||||||
|
# --- CHECKS ---
|
||||||
|
|
||||||
|
# 1. Intent Check
|
||||||
|
intent = data.get("intent", "UNKNOWN")
|
||||||
|
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}")
|
||||||
|
print(f" Erwartet: {expected_intent}")
|
||||||
|
print(f" Methode: {source_method}")
|
||||||
|
|
||||||
|
# 2. Source Check (Strategic Retrieval)
|
||||||
|
sources = data.get("sources", [])
|
||||||
|
strategic_hits = []
|
||||||
|
fact_hits = []
|
||||||
|
|
||||||
|
print(f"\n2. RETRIEVED SOURCES:")
|
||||||
|
if not sources:
|
||||||
|
print(" (Keine Quellen gefunden)")
|
||||||
|
|
||||||
|
debug_printed = False
|
||||||
|
|
||||||
|
for i, source in enumerate(sources):
|
||||||
|
# --- 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", "decision"]:
|
||||||
|
marker = "🎯" # Strategischer Treffer
|
||||||
|
strategic_hits.append(f"{title} ({node_type})")
|
||||||
|
else:
|
||||||
|
marker = "📄"
|
||||||
|
fact_hits.append(title)
|
||||||
|
|
||||||
|
print(f" {marker} [{i+1}] {title} (Typ: {node_type}, Score: {score:.2f})")
|
||||||
|
|
||||||
|
# Analyse der Strategie
|
||||||
|
if strategic_hits:
|
||||||
|
print(f"\n ✅ ERFOLG: Strategische Quellen geladen: {strategic_hits}")
|
||||||
|
else:
|
||||||
|
print(f"\n ℹ️ INFO: Keine strategischen Quellen (Value/Experience/etc.) gefunden.")
|
||||||
|
|
||||||
|
# 3. Reasoning Check (LLM Antwort)
|
||||||
|
answer = data.get("answer", "")
|
||||||
|
print(f"\n3. REASONING (LLM Antwort):")
|
||||||
|
print("-" * 60)
|
||||||
|
print(answer)
|
||||||
|
print("-" * 60)
|
||||||
|
|
||||||
|
except requests.exceptions.ReadTimeout:
|
||||||
|
print(f"\n❌ TIMEOUT: Der Server hat nicht innerhalb von 300s geantwortet.")
|
||||||
|
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?")
|
||||||
|
sys.exit(1)
|
||||||
|
except Exception as e:
|
||||||
|
print(f"\n❌ CRITICAL ERROR: {e}")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
parser = argparse.ArgumentParser(description="Testet die WP-06 Decision Engine.")
|
||||||
|
parser.add_argument("--query", "-q", type=str,
|
||||||
|
default="Soll ich SuperCloud Sync für meine privaten Tagebücher nutzen?",
|
||||||
|
help="Die Frage, die an das System gestellt wird.")
|
||||||
|
parser.add_argument("--port", "-p", type=int,
|
||||||
|
default=8002,
|
||||||
|
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, FACT).")
|
||||||
|
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
test_decision_engine(args.query, args.port, args.expect)
|
||||||
Reference in new issue
Block a user