diff --git a/docs/appendix.md b/docs/appendix.md new file mode 100644 index 0000000..4699cc1 --- /dev/null +++ b/docs/appendix.md @@ -0,0 +1,140 @@ +# Mindnet v2.2 – Appendices & Referenzen +**Datei:** `docs/mindnet_appendices_v2.2.md` +**Stand:** 2025-12-07 +**Status:** **FINAL** (Konsolidiert aus WP01–WP04a) +**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.2). Diese Werte werden beim Import angewendet, sofern im Frontmatter nichts anderes definiert ist. + +| 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. | +| **default** | `medium` | 1.00 | `references` | Fallback, wenn Typ unbekannt. | + +--- + +## Anhang B: Edge-Typen & Semantik + +Referenz aller implementierten Kantenarten (`kind`). Die Spalte "Herkunft" zeigt, durch welchen Mechanismus diese Kante primär entsteht. + +| 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) + +Dies sind die Felder, die effektiv in Qdrant gespeichert werden. Dient als Referenz für Entwickler und Debugging (`payload_dryrun`). + +### 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 + "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_HASH_COMPARE` | `Body` | Vergleichsmodus für Import (`Body`, `Frontmatter`, `Full`). | +| `MINDNET_HASH_SOURCE` | `parsed` | Quelle für Hash (`parsed`, `raw`, `file`). | +| `MINDNET_HASH_NORMALIZE` | `canonical` | Normalisierung vor Hash (`canonical`, `none`). | +| `VECTOR_DIM` | `384` | Dimension der Embeddings (Modellabhängig). | + +--- + +## Anhang E: Glossar + +Zentrale Begriffe des Mindnet-Systems. + +* **Callout-Edge:** Eine Kante, die durch einen Obsidian-Callout Block (`> [!edge]`) definiert wird. Dient für Listen. +* **Chunking:** Prozess des Zerlegens einer Notiz in kleinere, semantische Einheiten (Chunks). +* **Confidence:** Ein Wert (0.0-1.0), der angibt, wie sicher eine Kante ist. Explizite User-Eingaben haben 1.0, Defaults ~0.7. +* **Idempotenz:** Eigenschaft des Importers, bei mehrfacher Ausführung das exakt gleiche Ergebnis zu liefern (keine Duplikate). +* **Inline-Edge:** Eine Kante, die im Fließtext mittels `[[rel:type Ziel]]` definiert wird. Semantisch sehr stark. +* **Provenance:** Die Herkunft einer Information (z.B. "explicit" vs "rule" vs "inference"). +* **Retriever:** Die Komponente (FastAPI), die Suchanfragen beantwortet und Scores berechnet. +* **Rule ID:** Ein String, der genau identifiziert, welche Code-Regel eine Kante erzeugt hat (z.B. `edge_defaults:project:depends_on`). +* **Vault:** Der lokale Ordner mit Markdown-Dateien. Die "Single Source of Truth". +* **Vector Search:** Suche basierend auf semantischer Ähnlichkeit (Embeddings) statt reiner Stichworte. + +--- + +## Anhang F: Workpackage Status (v2.2) + +Status der Module gemäß Programmplan. + +| 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 | 🟡 In Arbeit | API liefert Pfade, UI fehlt noch. | +| **WP04c**| Feedback Loop | 🔴 Geplant | Logging von User-Feedback. | +| **WP05** | Virtual Schema | 🟡 Teilw. | `types.yaml` aktiv, ACL fehlt. | +| **WP06** | Self-Healing | 🔴 Geplant | Auto-Fixing von Broken Links. | +| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. | \ No newline at end of file