WP15c #18

Lars · 2025-12-31T16:56:25+01:00

Lars commented

2025-12-31 16:56:25 +01:00

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

# 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 ```

Lars added 2 commits 2025-12-31 16:56:26 +01:00

Implement WP-15c enhancements across graph and retrieval modules, including full metadata support for Super-Edge aggregation and Note-Level Diversity Pooling. Update scoring logic to reflect new edge handling and improve retrieval accuracy. Version updates to reflect these changes. d35bdc64b9

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. 4de9a4f649

Lars merged commit 67d7154328 into main

2025-12-31 16:56:36 +01:00

Lars referenced this issue from a commit

2025-12-31 16:56:38 +01:00

Merge pull request 'WP15c' (#18) from WP15c into main

Sign in to join this conversation.

No reviewers

No Label

No Milestone