@noyrax/5d-database-plugin 0.1.0

package/ADR_VORSCHLAEGE.md

@@ -0,0 +1,247 @@
+# ADR-Vorschläge für fehlende Dokumentation
+
+**Datum:** 2025-12-29  
+**Basis:** Gap Analysis Ergebnisse
+
+## Status-Übersicht
+
+### ✅ Bereits gut dokumentiert
+
+| Modul | Dependencies | ADRs | Status |
+|-------|--------------|------|--------|
+| `context-builder.ts` | 15 | ADR-025, ADR-035 | ✅ Gut dokumentiert |
+| `embedding-pipeline.ts` | 15 | ADR-021, ADR-030, ADR-032 | ✅ Gut dokumentiert |
+| `semantic-search-api.ts` | 5 | ADR-024, ADR-030, ADR-032 | ✅ Gut dokumentiert |
+| `semantic-discovery.ts` | 5 | ADR-028 | ✅ Dokumentiert |
+
+### ⚠️ Brauchen mehr Dokumentation
+
+| Rang | Modul | Dependencies | Aktuelle ADRs | Gap-Score | Empfehlung |
+|------|-------|--------------|---------------|-----------|------------|
+| 1 | `learning-path-api.ts` | 10 | ADR-026 | 10 | ⚠️ **Hoch** - Erweitern oder neues ADR |
+| 2 | `navigation-builder.ts` | 10 | ADR-023 | 10 | ⚠️ **Hoch** - Erweitern oder neues ADR |
+| 3 | `self-explanation-api.ts` | 8 | ADR-026 | 6 | ⚠️ **Mittel** - Erweitern |
+| 4 | `importance-scorer.ts` | 7 | ADR-022 | 4 | ⚠️ **Niedrig** - Könnte erweitert werden |
+
+---
+
+## Vorschläge für neue ADRs
+
+### Priorität 1: Module mit 10 Dependencies
+
+#### 1.1 `learning-path-api.ts` - Erweiterte Dokumentation
+
+**Aktueller Status:**
+- ADR-026: Self-Explanation und Learning Path (gemeinsam mit `self-explanation-api.ts`)
+- Gap-Score: 10 (10 Dependencies, 1 ADR)
+
+**Vorschlag: Neues ADR-036: Learning Path API - Dependency-basierte Lernpfade**
+
+**Inhalt:**
+- **Kontext:** Wie werden Lernpfade aus Dependency-Graph generiert?
+- **Entscheidung:** 
+  - Dependency-basierte Pfad-Generierung
+  - Entry Points als Startpunkte
+  - Semantic Search für Topic-Findung
+- **Konsequenzen:**
+  - Vorteile: Strukturierte Lernpfade, automatische Generierung
+  - Nachteile: Abhängig von Dependency-Graph-Qualität
+- **Alternativen:**
+  - Manuelle Lernpfade (zu aufwändig)
+  - KI-generierte Pfade (nicht deterministisch)
+
+**Oder:** ADR-026 erweitern um spezifische Details zu `learning-path-api.ts`
+
+#### 1.2 `navigation-builder.ts` - Erweiterte Dokumentation
+
+**Aktueller Status:**
+- ADR-023: Navigation Metadata - Entry Points, Clusters, ADR-Links
+- Gap-Score: 10 (10 Dependencies, 1 ADR)
+
+**Vorschlag: ADR-023 erweitern oder neues ADR-037: Navigation Builder - Automatische Metadata-Generierung**
+
+**Inhalt:**
+- **Kontext:** Wie werden Navigation Metadata automatisch generiert?
+- **Entscheidung:**
+  - Entry Points: Importance Score + Dependency-Analyse
+  - Clusters: Verzeichnisstruktur-basiert
+  - ADR-Links: Via AdrFileMapping
+- **Konsequenzen:**
+  - Vorteile: Automatische Generierung, konsistente Navigation
+  - Nachteile: Clustering basiert nur auf Verzeichnisstruktur
+- **Alternativen:**
+  - Semantisches Clustering (komplexer, langsamer)
+  - Manuelle Metadata (wartungsaufwändig)
+
+**Oder:** ADR-023 erweitern um Implementierungsdetails zu `navigation-builder.ts`
+
+### Priorität 2: Module mit 7-8 Dependencies
+
+#### 2.1 `self-explanation-api.ts` - Erweiterte Dokumentation
+
+**Aktueller Status:**
+- ADR-026: Self-Explanation und Learning Path (gemeinsam mit `learning-path-api.ts`)
+- Gap-Score: 6 (8 Dependencies, 1 ADR)
+
+**Vorschlag: ADR-026 erweitern um Self-Explanation-spezifische Details**
+
+**Neue Abschnitte für ADR-026:**
+- **Self-Explanation API Details:**
+  - Entry Points Identifikation
+  - System-Übersicht Generierung
+  - Architecture ADRs Integration
+- **Unterschied zu Learning Path:**
+  - Self-Explanation: System-Übersicht (statisch)
+  - Learning Path: Geführter Pfad (dynamisch)
+
+#### 2.2 `importance-scorer.ts` - Erweiterte Dokumentation
+
+**Aktueller Status:**
+- ADR-022: Importance Scoring - PageRank und Betweenness Centrality
+- Gap-Score: 4 (7 Dependencies, 1 ADR)
+
+**Vorschlag: ADR-022 erweitern um Implementierungsdetails**
+
+**Neue Abschnitte für ADR-022:**
+- **Implementierungsdetails:**
+  - PageRank-Algorithmus: Iterativ bis Konvergenz
+  - Betweenness Centrality: Vereinfachte Implementierung (O(n))
+  - Score-Kombination: 70% PageRank + 30% Betweenness
+- **Performance:**
+  - Incremental Updates nur bei Dependency-Änderungen
+  - Caching-Strategie
+
+---
+
+## Empfohlene Vorgehensweise
+
+### Option A: Neue ADRs erstellen (empfohlen für Priorität 1)
+
+**Vorteile:**
+- Klare Trennung der Themen
+- Spezifische Dokumentation pro Modul
+- Bessere Auffindbarkeit
+
+**Nachteile:**
+- Mehr ADRs zu pflegen
+- Potenzielle Redundanz
+
+**Empfehlung für:**
+- `learning-path-api.ts` → ADR-036
+- `navigation-builder.ts` → ADR-037 (oder ADR-023 erweitern)
+
+### Option B: Bestehende ADRs erweitern (empfohlen für Priorität 2)
+
+**Vorteile:**
+- Weniger ADRs
+- Zusammenhängende Themen zusammen
+
+**Nachteile:**
+- Längere ADRs
+- Möglicherweise weniger spezifisch
+
+**Empfehlung für:**
+- `self-explanation-api.ts` → ADR-026 erweitern
+- `importance-scorer.ts` → ADR-022 erweitern
+
+---
+
+## Konkrete ADR-Vorschläge
+
+### ADR-036: Learning Path API - Dependency-basierte Lernpfade
+
+**Status:** Proposed
+
+**Kontext:**
+- LLM-Agenten benötigen geführte Lernpfade durch das System
+- Dependency-Graph liefert natürliche Abhängigkeits-Struktur
+- Entry Points als Startpunkte für Lernpfade
+
+**Entscheidung:**
+- **LearningPathApi** (`src/api/learning-path-api.ts`):
+  - Generiert Lernpfade basierend auf Dependency-Graph
+  - Nutzt Entry Points als Startpunkte
+  - Semantic Search für Topic-Findung
+  - Dependency-Pfad-Generierung (From → To)
+
+**Konsequenzen:**
+- ✅ Automatische Lernpfad-Generierung
+- ✅ Strukturierte Navigation durch System
+- ⚠️ Abhängig von Dependency-Graph-Qualität
+- ⚠️ O(n) für Semantic Search + Dependency-Pfad
+
+**Alternativen:**
+- Manuelle Lernpfade (zu aufwändig)
+- KI-generierte Pfade (nicht deterministisch)
+
+**Verweise:**
+- ADR-026: Self-Explanation und Learning Path (gemeinsam dokumentiert)
+- ADR-024: Semantic Search API (nutzt für Topic-Findung)
+- ADR-023: Navigation Metadata (nutzt Entry Points)
+
+---
+
+### ADR-037: Navigation Builder - Automatische Metadata-Generierung
+
+**Status:** Proposed
+
+**Kontext:**
+- Navigation Metadata (Entry Points, Clusters, ADR-Links) müssen automatisch generiert werden
+- Importance Scores liefern Basis für Entry Point Identifikation
+- AdrFileMapping liefert ADR-Links
+
+**Entscheidung:**
+- **NavigationBuilder** (`src/services/navigation-builder.ts`):
+  - Entry Points: Importance Score > 0.1 + keine eingehenden Dependencies
+  - Clusters: Verzeichnisstruktur-basiert (`cluster:{directory_path}`)
+  - ADR-Links: Via `AdrFileMapping` aus W-Dimension
+
+**Konsequenzen:**
+- ✅ Automatische Generierung
+- ✅ Konsistente Navigation
+- ⚠️ Clustering basiert nur auf Verzeichnisstruktur (einfach)
+- ⚠️ Entry Points möglicherweise nicht optimal
+
+**Alternativen:**
+- Semantisches Clustering (komplexer, langsamer)
+- Manuelle Metadata (wartungsaufwändig)
+
+**Verweise:**
+- ADR-023: Navigation Metadata (High-Level-Entscheidung)
+- ADR-022: Importance Scoring (nutzt für Entry Points)
+- ADR-025: Deterministic Context Builder (nutzt Navigation Metadata)
+
+---
+
+## Zusammenfassung
+
+### Sofort umsetzen (Priorität 1)
+
+1. **ADR-036: Learning Path API** (neu)
+   - Dokumentiert `learning-path-api.ts` spezifisch
+   - Ergänzt ADR-026
+
+2. **ADR-037: Navigation Builder** (neu) ODER **ADR-023 erweitern**
+   - Dokumentiert `navigation-builder.ts` spezifisch
+   - Ergänzt ADR-023
+
+### Später umsetzen (Priorität 2)
+
+3. **ADR-026 erweitern** um Self-Explanation-spezifische Details
+4. **ADR-022 erweitern** um Implementierungsdetails
+
+### Optional (Priorität 3)
+
+- Weitere Module mit 5 Dependencies prüfen
+- Gap Analysis regelmäßig ausführen
+
+---
+
+**Nächste Schritte:**
+1. ADR-036 erstellen (Learning Path API)
+2. ADR-037 erstellen (Navigation Builder) ODER ADR-023 erweitern
+3. ADR-026 erweitern (Self-Explanation Details)
+4. ADR-022 erweitern (Importance Scorer Details)
+5. Re-Ingestion ausführen (File-Mappings aktualisieren)
+6. Gap Analysis erneut ausführen (Verifikation)
+

package/CHROMADB_SETUP.md

@@ -0,0 +1,69 @@
+# ChromaDB Setup für Windows
+
+ChromaDB wird auf Windows als Vektordatenbank verwendet, da SQLite VSS auf Windows nicht unterstützt wird.
+
+## Installation
+
+### ChromaDB Server Mode (empfohlen)
+
+1. **Python installieren** (Version 3.9 oder höher)
+   - Download von: https://www.python.org/downloads/
+
+2. **ChromaDB installieren**
+   ```bash
+   pip install chromadb
+   ```
+
+3. **ChromaDB Server starten**
+   ```bash
+   chroma run --host localhost --port 8000
+   ```
+   
+   **Wichtig:** Der Server muss laufen, damit die VS Code Extension ChromaDB verwenden kann.
+   Sie können den Server im Hintergrund laufen lassen oder als Windows Service einrichten.
+
+4. **npm Package installieren** (JavaScript Client)
+   ```bash
+   cd 5d-database-plugin
+   npm install chromadb
+   ```
+
+**Hinweis:** Die ChromaDB-Implementierung verbindet sich mit `http://localhost:8000`.
+Stellen Sie sicher, dass der Server läuft, bevor Sie die Extension verwenden.
+
+## Verwendung
+
+Die ChromaDB-Integration ist automatisch aktiviert auf Windows. 
+Das System verwendet automatisch ChromaDB, wenn:
+- `process.platform === 'win32'`
+- ChromaDB-Package installiert ist
+- ChromaDB erfolgreich initialisiert werden kann
+
+Falls ChromaDB nicht verfügbar ist, fällt das System automatisch auf Cosine Similarity zurück.
+
+## Troubleshooting
+
+### ChromaDB kann nicht initialisiert werden
+
+- Prüfen Sie, ob Python installiert ist: `python --version`
+- Prüfen Sie, ob ChromaDB installiert ist: `pip list | grep chromadb`
+- Prüfen Sie, ob das npm Package installiert ist: `npm list chromadb`
+
+### ChromaDB Server läuft nicht
+
+Wenn Sie ChromaDB als Server verwenden möchten:
+1. Starten Sie den Server: `chroma run --host localhost --port 8000`
+2. Stellen Sie sicher, dass Port 8000 frei ist
+
+### Embedded Mode Probleme
+
+Wenn Embedded Mode nicht funktioniert:
+- Prüfen Sie, ob Python auf dem PATH ist
+- Prüfen Sie, ob `chromadb` Python Package installiert ist
+- Prüfen Sie die Berechtigungen für `.database-plugin/chromadb/`
+
+## Weitere Informationen
+
+- [ChromaDB Dokumentation](https://docs.trychroma.com/)
+- [ChromaDB GitHub](https://github.com/chroma-core/chroma)
+