Update documentation to version 2.9.1, incorporating WP-15c enhancements including section-based links, multigraph support, and improved scoring logic. Add details on Super-Edge aggregation and Note-Level Diversity Pooling for better retrieval accuracy. Enhance context descriptions and clarify provenance handling in technical references.
This commit is contained in:
1 parent
d35bdc64b9
commit
4de9a4f649
5 files changed
+448
-21
No files matched your search
@@ -0,0 +1,123 @@
|
||||
# Branch Merge Commit Message: WP15c
|
||||
|
||||
```
|
||||
feat: Multigraph-Support, Diversity Engine & Provenance Firewall (v2.9.1)
|
||||
|
||||
## Graph Topology & Edge Management (WP-15c)
|
||||
|
||||
### Section-Präzision & Multigraph-Modus
|
||||
- Präzise Erkennung von Obsidian-Ankern (`[[Note#Section]]`) und Self-Links (`[[#Section]]`)
|
||||
- Links werden in `target_id="Note"` und `target_section="Section"` aufgelöst
|
||||
- Edge-ID enthält `variant` (Section) für eindeutige Identifikation
|
||||
- Multigraph-Modus: Mehrere Kanten zwischen denselben Notizen möglich, wenn sie auf verschiedene Sections zeigen
|
||||
- Behebt "Phantom-Knoten" durch korrekte Trennung von Note-Name und Abschnitt
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/core/graph/graph_utils.py`: `parse_link_target()` für Section-Extraktion & Self-Links (v1.1.2)
|
||||
- `app/core/graph/graph_derive_edges.py`: Multigraph-Support, `target_section` in Edge-Payload (v1.1.2)
|
||||
- `app/core/graph/graph_subgraph.py`: Metadaten-Persistenz (v1.2.0)
|
||||
- `app/core/graph/graph_db_adapter.py`: Vollständige Metadaten-Durchreichung (v1.1.1)
|
||||
|
||||
### Provenance Firewall (Edge Registry v0.8.0)
|
||||
- System-Kanten (`next`, `prev`, `belongs_to`) dürfen nur mit `provenance="structure"` gesetzt werden
|
||||
- Alle anderen Provenienzen (`explicit`, `semantic_ai`, `inherited`, `global_pool`, `rule`) werden blockiert
|
||||
- Automatischer Fallback auf `related_to` bei unerlaubter Verwendung
|
||||
- Logging in `data/logs/unknown_edges.jsonl` für Admin-Review
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/services/edge_registry.py`: Provenance Firewall (v0.8.0)
|
||||
|
||||
## Retrieval-Intelligenz (The Diversity Engine)
|
||||
|
||||
### Note-Level Diversity Pooling
|
||||
- Pro `note_id` wird nur der relevanteste Treffer im Endergebnis behalten
|
||||
- Verhindert "Note-Flooding" (Dominanz einer einzigen Notiz durch viele ähnliche Chunks)
|
||||
- Workflow: Sortierung nach finalem Score → Diversity-Pooling → Begrenzung auf `top_k`
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/core/retrieval/retriever.py`: Note-Level Diversity Pooling (v0.7.0)
|
||||
|
||||
### Super-Edge Aggregation
|
||||
- Parallele Kanten zwischen zwei Notizen werden mathematisch zu einer "Super-Edge" aggregiert
|
||||
- Primäre Kante zählt voll, weitere Kanten werden mit Dämpfungsfaktor **0.1** gewichtet
|
||||
- Verhindert Score-Explosionen durch multiple Links auf verschiedene Sections
|
||||
- Metadaten: `is_super_edge` Flag und `edge_count` für Explanation Layer
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/core/retrieval/retriever.py`: Super-Edge Aggregation (v0.7.0)
|
||||
|
||||
### Metadaten-Persistenz
|
||||
- In-Memory Subgraph und Datenbank-Adapter erweitert für durchgängige Metadaten-Erhaltung
|
||||
- `target_section`, `provenance` und `confidence` werden vollständig erhalten
|
||||
- Ermöglicht präzises Retrieval-Reasoning und Explanation Layer
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/core/graph/graph_subgraph.py`: Metadaten-Persistenz (v1.2.0)
|
||||
- `app/core/graph/graph_db_adapter.py`: Vollständige Metadaten-Durchreichung (v1.1.1)
|
||||
|
||||
## Mathematisches Scoring (WP-22 Integration)
|
||||
|
||||
### Hybrid Scoring Formula (v1.0.3)
|
||||
- Neue Formel: `Final = (Semantic * StatusMult) * (1 + TypeBoost + EdgeBonus + CentBonus)`
|
||||
- Status-Gatekeeper: `stable` = 1.2, `draft` = 0.5, `active` = 1.0
|
||||
- Graph Boost Factor: Intent-spezifische Verstärkung (1.5x bei aktivem Intent)
|
||||
- Status wirkt als Multiplikator auf die Basis-Relevanz, Graph-Boni werden proportional verstärkt
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/core/retrieval/retriever_scoring.py`: Hybrid Scoring Formula (v1.0.3)
|
||||
|
||||
### Explanation Layer
|
||||
- Detaillierte Begründungen für jeden Bonus (Sektions-Links, Hub-Zentralität, Super-Edge-Informationen)
|
||||
- Provenance-Informationen für erhöhte Transparenz
|
||||
- Massiv erhöhte Transparenz für Debugging und Nutzer-Vertrauen
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/core/retrieval/retriever.py`: Explanation Layer (v0.7.0)
|
||||
|
||||
## Ingestion & Profil-Synchronisation
|
||||
|
||||
### Registry-First Profiling (v2.13.12)
|
||||
- Hierarchische Auflösung: Frontmatter > types.yaml Typ-Config > Global Defaults
|
||||
- Konsistente Verarbeitung je nach Notiz-Typ
|
||||
- Note-Typen wie `value` erhalten automatisch das korrekte Profil (`structured_smart_edges_strict`)
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/core/ingestion/ingestion_processor.py`: Registry-First Profiling (v2.13.12)
|
||||
|
||||
## Impact & Breaking Changes
|
||||
|
||||
### Keine Migration erforderlich
|
||||
**WICHTIG:** Diese Version ist **rückwärtskompatibel**. Bestehende Vaults funktionieren ohne Re-Import.
|
||||
|
||||
**Empfehlung:** Optionaler Re-Import für optimale Nutzung der neuen Features:
|
||||
```bash
|
||||
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||||
```
|
||||
|
||||
### Fixes
|
||||
- ✅ Resolves: "Phantom-Knoten" durch korrekte Trennung von Note-Name und Section
|
||||
- ✅ Resolves: Score-Explosionen durch multiple Links auf verschiedene Sections
|
||||
- ✅ Resolves: "Note-Flooding" durch fehlende Diversity-Filterung
|
||||
- ✅ Resolves: Inkonsistente Metadaten durch fehlende Persistenz im Subgraph
|
||||
- ✅ Resolves: Manipulation von System-Kanten durch Provenance Firewall
|
||||
|
||||
## Dokumentation
|
||||
|
||||
Alle relevanten Dokumente aktualisiert:
|
||||
- `02_concept_graph_logic.md`: Provenance Firewall, Self-Links, Multigraph-Support
|
||||
- `03_tech_retrieval_scoring.md`: Hybrid Scoring Formula, Note-Level Diversity, Super-Edge Aggregation
|
||||
- `03_tech_data_model.md`: Section-Support, Metadaten-Persistenz
|
||||
- `03_tech_ingestion_pipeline.md`: Registry-First Profiling (bereits dokumentiert)
|
||||
|
||||
## Versionen
|
||||
|
||||
- Edge Registry: v0.8.0
|
||||
- Graph Utils / Derive Edges: v1.1.2
|
||||
- Graph Subgraph: v1.2.0
|
||||
- Graph DB Adapter: v1.1.1
|
||||
- Retriever: v0.7.0
|
||||
- Retriever Scoring: v1.0.3
|
||||
- Ingestion Processor: v2.13.12
|
||||
|
||||
Closes #[issue-number]
|
||||
```
|
||||
Reference in new issue
Block a user