Compare commits

...
2 Commits
Author SHA1 Message Date
Lars 5b9399361d Programmmanagement/Programmplan_V2.2.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 06:59:40 +01:00
Lars d49da1b5fe docs/dev_workflow.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-07 18:53:13 +01:00
2 changed files with 119 additions and 364 deletions

No files matched your search

+75 -334
View File
@@ -1,7 +1,7 @@
# mindnet v2.2 — Programmplan # mindnet v2.2 — Programmplan
**Version:** 2.2 **Version:** 2.2.1 (Post-WP04 Update)
**Stand:** 2025-12-06 **Stand:** 2025-12-07
**Status:** Aktiv (Fortschreibung von v2.1) **Status:** Aktiv
--- ---
@@ -72,10 +72,12 @@ Kernprinzipien der Vision:
- Automatische Sammlung von Wissen aus Markdown-Vault und ersten Chat-Dialogen. - Automatische Sammlung von Wissen aus Markdown-Vault und ersten Chat-Dialogen.
- Aufbau eines stabilen Graph-Speichers in Qdrant (`*_notes`, `*_chunks`, `*_edges`). - Aufbau eines stabilen Graph-Speichers in Qdrant (`*_notes`, `*_chunks`, `*_edges`).
- Semantischer und graphbasierter Retriever (WP-04a abgeschlossen, WP-04b/04c in Vorbereitung). - 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).
- Automatisierte Erkennung von Beziehungen: - Automatisierte Erkennung von Beziehungen:
- Wikilinks, Inline-Relationen, Callout-Edges, Typ-Defaults. - Wikilinks, Inline-Relationen, Callout-Edges, Typ-Defaults.
- Schrittweises Lernen über Feedback (Score-Tuning, noch „manuell“ konfiguriert). :contentReference[oaicite:8]{index=8} - Schrittweises Lernen über Feedback (Score-Tuning, noch „manuell“ konfiguriert).
- „Mitwachsendes“ Schema ohne Obsidian-Umstrukturierungen: - „Mitwachsendes“ Schema ohne Obsidian-Umstrukturierungen:
- Neues Wissen kann sofort erfasst werden, - Neues Wissen kann sofort erfasst werden,
- bestehende Notizen bleiben gültig (Virtual Schema Layer). - bestehende Notizen bleiben gültig (Virtual Schema Layer).
@@ -87,6 +89,7 @@ Kernprinzipien der Vision:
### 3.2 Mittelfristig ### 3.2 Mittelfristig
- Persönlichkeitsprofil wird stabil erkannt und für Antworten genutzt (Typen, Werte-Notizen, Entscheidungsnotizen). - Persönlichkeitsprofil wird stabil erkannt und für Antworten genutzt (Typen, Werte-Notizen, Entscheidungsnotizen).
- **RAG-Chat:** KI antwortet in natürlicher Sprache auf Basis von Wissen und Persönlichkeit (WP-05).
- Why-Layer: KI-Assistenz für Entscheidungen mit nachvollziehbarer Argumentation. - Why-Layer: KI-Assistenz für Entscheidungen mit nachvollziehbarer Argumentation.
- Interview-Assistent erstellt neue Notes automatisch (strukturierte Dialoge → Markdown). - 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. - mindnet erzeugt Vorschläge für neue Notes & Edges und bietet einen „Vernetzungs-Assistenten“ für manuell angelegte Notizen.
@@ -156,7 +159,7 @@ Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen:
Phase D – Agenten, MCP & Interaktion Phase D – Agenten, MCP & Interaktion
Phase E – Review, Refactoring, Dokumentation Phase E – Review, Refactoring, Dokumentation
Alle Workpackages sind einer Phase zugeordnet; einige Workpackages (z. B. WP-03, WP-04a) sind bereits abgeschlossen und bilden heute die Basis für alle weiteren Schritte. Alle Workpackages sind einer Phase zugeordnet. WP-01 bis WP-04c sind bereits erfolgreich abgeschlossen.
--- ---
@@ -167,7 +170,7 @@ Alle Workpackages sind einer Phase zugeordnet; einige Workpackages (z. B. WP-03,
- Aufwand: Niedrig / Mittel / Hoch - Aufwand: Niedrig / Mittel / Hoch
- Komplexität: Niedrig / Mittel / Hoch - Komplexität: Niedrig / Mittel / Hoch
Die Status-Ampel zeigt den aktuellen Stand gemäß Programmfortschritt. :contentReference[oaicite:18]{index=18} Die Status-Ampel zeigt den aktuellen Stand gemäß Programmfortschritt.
--- ---
@@ -178,33 +181,12 @@ Die Status-Ampel zeigt den aktuellen Stand gemäß Programmfortschritt. :content
**Ziel:** **Ziel:**
Grundlegendes Schema für mindnet festlegen (`knowledge_design.md`), inkl.: 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.
- Note-Typen (z. B. `concept`, `experience`, `project`, `decision`, `value`, `principle`, `person`, `event`, etc.). **Erreichte Ergebnisse:**
- Standard-Properties (Titel, Typ, Tags, Status, Zeitstempel, Referenzen, Policies). - `knowledge_design.md` und `types.yaml` definieren die Zielarchitektur.
- Grundstruktur von Edges (z. B. `belongs_to`, `references`, `depends_on`, `similar_to`, `related_to`, `influenced_by`).
- Abbildung zentraler Lebens-Bereiche, Rollen und Wissenskategorien.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel
**Erreichte Ergebnisse / Funktionsumfang:**
- `knowledge_design.md` in Version 1.5 definiert:
- Zielarchitektur,
- Collections,
- Identitätsmodell,
- zentrale Typen und Edges. :contentReference[oaicite:20]{index=20}
- Das Dokument beschreibt klar:
- wie Wissen fachlich strukturiert wird,
- welche Typen und Relationen in mindnet „erwartet“ werden,
- wie spätere Erweiterungen (neue Typen, zusätzliche Edge-Arten) ohne Retro-Migration möglich sind.
**DoD:**
- Schema ist konsistent beschrieben.
- Grundtypen und Edge-Arten sind definiert und im Code konzeptionell verankert (z. B. via `types.yaml`).
- Das Dokument dient als Referenz für alle folgenden WPs.
--- ---
@@ -214,32 +196,11 @@ Grundlegendes Schema für mindnet festlegen (`knowledge_design.md`), inkl.:
**Status:** 🟢 abgeschlossen **Status:** 🟢 abgeschlossen
**Ziel:** **Ziel:**
Festlegen und implementieren einer robusten Chunking-Strategie und einer Hash-Logik zur Änderungs­erkennung. Festlegen und implementieren einer robusten Chunking-Strategie und einer Hash-Logik zur Änderungserkennung.
**Umfang (fachlich & technisch):** **Erreichte Ergebnisse:**
- Implementierte Chunker-Logik mit Overlap.
- Text in semantisch sinnvolle Chunks teilen (Heading-/Block-aware). - Stabile Hash-Strategie zur sicheren Änderungserkennung.
- Parallelhaltung von:
- `text` (Chunk-Kern ohne Overlap),
- `window` (Chunk-Fenster mit Overlap für Embeddings).
- Hash-Modi zur Änderungs­erkennung (Body / Frontmatter / Full, canonical vs. none).
- Unterstützung eines „Baseline-Modus“ (mehrere Hash-Signaturen), um spätere Modus-Wechsel zu ermöglichen, ohne alle Notizen als „geändert“ zu sehen.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel/Hoch
**Erreichte Ergebnisse / Funktionsumfang:**
- Implementierte Chunker-Logik mit Ziel-Längen, Overlap und Nachbarschaft (`neighbors_prev`, `neighbors_next`).
- Tests zur Überprüfung der Rekonstruktion von Notiz-Bodies aus Chunks (`verify_chunks_integrity.py`, `check_chunks_window_vs_text.py`).
- Hash-Konfiguration über ENV-Variablen + Option `--baseline-modes`.
- Roundtrip-Tests für Vault → Qdrant → Export-Vault (keine ungewollten Veränderungen an Inhalten).
**DoD:**
- Chunking stabil, deterministisch, überprüft.
- Hash-Strategie ermöglicht sichere Änderungs­erkennung ohne Mass-Diffs bei Konfigurationswechsel.
--- ---
@@ -249,39 +210,11 @@ Festlegen und implementieren einer robusten Chunking-Strategie und einer Hash-Lo
**Status:** 🟢 abgeschlossen **Status:** 🟢 abgeschlossen
**Ziel:** **Ziel:**
Durchgängige Import-Pipeline von Markdown → Notes/Chunks/Edges in Qdrant mit deterministischen IDs, typbasierten Defaults und erklärbarem Edge-Modell. Durchgängige Import-Pipeline von Markdown → Notes/Chunks/Edges in Qdrant mit deterministischen IDs.
**Umfang:** **Erreichte Ergebnisse:**
- Vollständige E2E-Import-Pipeline.
- Parser (robust gegenüber Zeichensatzfehlern, Frontmatter/Body-Erkennung, Sonderfälle wie Silverbullet-Dateien). - Vollständiges Edge-Modell (Strukturkanten, Wikilinks, Inline-Relationen).
- Bau von Note-Payloads (`note_payload`):
- Typ-Vererbung (`retriever_weight`, `chunk_profile`, `edge_defaults`).
- Bau von Chunk-Payloads (`chunk_payload`):
- `text`, `window`, Nachbarn, Typ-Information.
- Edge-System:
- Strukturkanten (`belongs_to`, `next`, `prev`),
- explizite Wikilinks (`[[Note]]` → `references`),
- Inline-Relationen (`[[rel:depends_on Note]]`),
- Callout-Edges (`> [!edge] related_to: [[Note]]`),
- typbasierte Standardkanten aus `types.yaml` (`edge_defaults`).
- Idempotente Upserts in Qdrant (Notes/Chunks/Edges).
**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch
**Erreichte Ergebnisse / Funktionsumfang:**
- Vollständige E2E-Import-Pipeline incl. Tests (`run_e2e_roundtrip.sh`, `compare_vaults.py`, `validate_edges`, `edges_full_check`).
- deterministische ID-Vergabe für Notes/Chunks/Edges.
- vollständiges Edge-Modell gemäß Facharchitektur (`mindnet_functional_architecture.md`). :contentReference[oaicite:26]{index=26}
- Exporte zurück nach Markdown (Export-Pipeline) ermöglicht Roundtrip-Vergleich.
**DoD:**
- Importer generiert stabile Notes/Chunks/Edges für gesamten Vault.
- Edge-Invarianten (`belongs_to == #Chunks`, `next/prev` konsistent) erfüllt.
- Roundtrip: Exportierte Vault-Version stimmt inhaltlich mit originalem Vault überein (bis auf bewusst ausgeschlossene Dateien).
--- ---
@@ -291,132 +224,64 @@ Durchgängige Import-Pipeline von Markdown → Notes/Chunks/Edges in Qdrant mit
**Status:** 🟢 abgeschlossen **Status:** 🟢 abgeschlossen
**Ziel:** **Ziel:**
Aufbau eines hybriden Retrievers, der Semantik (Embeddings), Typwissen (`retriever_weight`) und Graph-Informationen (Edges, Centrality) zu einem erklärbaren Score kombiniert. Aufbau eines hybriden Retrievers, der Semantik, Typwissen und Graph-Informationen kombiniert.
**Umfang:** **Erreichte Ergebnisse:**
- Hybrides Scoring-Modell (Semantic + Edge + Centrality).
- Retriever-Modul (`app/core/retriever.py`): - Konfiguration über `retriever.yaml`.
- Vektorsuche über `*_chunks`, - `/query` Endpoint aktiv.
- Zusammenführung von Chunk-Treffern mit Note-Metadaten,
- Aufbau eines Subgraphen (Nachbarn über Edges, Centrality-Berechnung).
- Scoring-Formel:
semantic_score
retriever_weight
edge_bonus
centrality_bonus
- Konfiguration über `config/retriever.yaml` (Gewichte, Parameter). :contentReference[oaicite:28]{index=28}
- FastAPI-Endpoint `/query` mit Rückgabe:
- Trefferliste,
- Teil-Scores,
- Begründung (inkl. Edge-Kontext).
**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch
**Erreichte Ergebnisse / Funktionsumfang:**
- Hybrides Scoring-Modell mit konfigurierbaren Gewichten (`semantic_weight`, `edge_weight`, `centrality_weight`).
- Nutzung von `retriever_weight` aus `types.yaml` in Score-Berechnung.
- Graph-boni aus echten Edges (explizit, Inline, Typ-Defaults, Strukturkanten).
- Funktionsfähiger `/query`-Endpoint mit Testcases (inkl. Relations-Showcase-Vault).
- Basis für spätere Self-Tuning-Mechanismen (Logging von Scores, Konfiguration in `retriever.yaml`).
**DoD:**
- `/query` liefert nachvollziehbare Ergebnisse mit sichtbarem Einfluss von:
- Typprioritäten,
- Edge-Struktur,
- Centrality.
- Scoring ist rein konfigurierbar (Konfig-Change → Score-Veränderung ohne Code-Änderung).
--- ---
### WP-04b – Explanation Layer (geplant) ### WP-04b – Explanation Layer ("Why-Layer") (abgeschlossen)
**Phase:** B **Phase:** B
**Status:** 🟡 geplant **Status:** 🟢 abgeschlossen (Neu)
**Ziel:** **Ziel:**
Treffererklärungen liefern, die für dich (Mindmaster) und spätere Nutzer verständlich sind (Why-Layer). Treffererklärungen liefern, die verständlich machen, warum ein Ergebnis gewählt wurde.
**Umfang:** **Erreichte Ergebnisse:**
- **DTO-Erweiterung:** `QueryHit` enthält `explanation`, `breakdown` und `reason`.
- Erklärungsschicht über dem Retriever: - **Logic:** Graph-Adapter unterstützt `incoming_edges` (Reverse Lookup) für Authority-Erklärungen.
- Aufschlüsselung des Scores pro Treffer, - **Output:** `/query` Endpoint liefert auf Wunsch (`explain: true`) menschenlesbare Begründungen ("Verweist auf...").
- Ketten von Edges (Pfade) als Begründungsgraph,
- Markierung relevanter Chunks / Notizen.
- Darstellung von:
- verwendeten Typen,
- Edges und deren `rule_id` / `confidence`,
- Centrality-Beiträgen.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Hoch
**DoD (Zielbild):**
- API-Endpoint (z. B. `/query/explain`), der eine strukturierte Erklärung in JSON liefert.
- Mindestens ein Beispiel, in dem Score-Änderung nachvollziehbar auf Policies/Edges zurückgeführt werden kann.
--- ---
### WP-04c – Feedback Logging & Bewertungsdaten (geplant) ### WP-04c – Feedback Logging & Bewertungsdaten (abgeschlossen)
**Phase:** B **Phase:** B
**Status:** 🟡 geplant **Status:** 🟢 abgeschlossen (Neu)
**Ziel:** **Ziel:**
Grundlage für Self-Tuning schaffen, indem Queries, Antworten und Bewertungen systematisch protokolliert werden. Grundlage für Self-Tuning schaffen durch systematisches Logging.
**Umfang:** **Erreichte Ergebnisse:**
- **Data Flywheel:** Logging von Queries und User-Feedback in lokalen JSONL-Dateien.
- Logging von: - **Search Log:** Speichert Query + Score-Snapshot in `data/logs/search_history.jsonl`.
- Query-Texten, - **Feedback Log:** Speichert User-Ratings in `data/logs/feedback.jsonl`.
- verwendeten Policies/Config-Versionen, - **Traceability:** Durchgängige `query_id` von Request bis Feedback.
- Trefferlisten (Scores, Edges),
- Feedback (z. B. „hilfreich“, „irrelevant“, „falsch“).
- Persistente Speicherung (z. B. in einer separaten Sammlung oder Datei-basiert).
- Bereitstellung von Auswertungs-Skripten (Statistiken, Ranking-Qualität).
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel/Hoch
**DoD (Zielbild):**
- Vollständiger Feedback-Trail für ausgewählte Test-Sessions.
- Exportfähige Datenbasis zur späteren Optimierung der Retriever-Parameter.
--- ---
### WP-05 – Persönlichkeitsmodell (geplant) ### WP-05 – Persönlichkeitsmodell & RAG-Chat (Startbereit)
**Phase:** C **Phase:** C
**Status:** 🟡 geplant **Status:** 🟡 geplant (Nächster Schritt)
**Ziel:** **Ziel:**
Aufbau eines expliziten Persönlichkeitsmodells, das Werte, Prinzipien, prägende Erfahrungen und wiederkehrende Entscheidungsstrategien abbildet. Aufbau eines RAG-Systems, das nicht nur sucht, sondern in natürlicher Sprache antwortet und dabei eine definierte Persönlichkeit (Werte, Prinzipien) einnimmt.
**Umfang:** **Umfang:**
- **Config:** `config/prompts.yaml` für System-Prompts, Werte und RAG-Templates.
- Identifikation und Typisierung relevanter Notes: - **Service:** `llm_service.py` für Text-Generierung (Ollama-Anbindung).
- `value`, `principle`, `life_event`, `milestone`, `decision`. - **Router:** `/chat` Endpoint (Kontext-Assembly -> Prompt -> LLM).
- Aufbau eines Modells, das: - **Persönlichkeit:** Definition von "Mindnet" als KI-Zwilling (Stil, Haltung).
- typische Begründungsmuster erkennt,
- Wertprioritäten identifiziert,
- langfristig in Scoring & Antwort-Formulierung einfließt.
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Mittel - Aufwand: Mittel
- Komplexität: Mittel - Komplexität: Mittel
**DoD (Zielbild):**
- Dokumentiertes Persönlichkeitsmodell (z. B. YAML/Markdown), das konkrete Wert-/Prinzipien-Strukturen beschreibt.
- Basis-Integration in den Retriever (z. B. Wert-Bezüge in Explanation-Layer).
--- ---
### WP-06 – Decision Engine (geplant) ### WP-06 – Decision Engine (geplant)
@@ -428,23 +293,14 @@ Aufbau eines expliziten Persönlichkeitsmodells, das Werte, Prinzipien, prägend
Entscheidungsunterstützung auf Basis von Wissen, Persönlichkeit und Zielen – inklusive nachvollziehbarer Begründung. Entscheidungsunterstützung auf Basis von Wissen, Persönlichkeit und Zielen – inklusive nachvollziehbarer Begründung.
**Umfang:** **Umfang:**
- Identifikation typischer Entscheidungssituationen.
- Identifikation typischer Entscheidungssituationen (z. B. beruflich, familiär, gesundheitlich). - Integration von fachlichem Wissen, Erfahrungen und Persönlichkeitsmodell.
- Integration von:
- fachlichem Wissen,
- Erfahrungen (Vergangenheitsentscheidungen),
- Persönlichkeitsmodell.
- Ableitung von Entscheidungs-Templates / Heuristiken. - Ableitung von Entscheidungs-Templates / Heuristiken.
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Mittel - Aufwand: Mittel
- Komplexität: Hoch - Komplexität: Hoch
**DoD (Zielbild):**
- Prototypischer „Decision-Assistant“, der für definierte Szenarien begründete Empfehlungen gibt.
- Erklärungen referenzieren konkrete Notes/Edges.
--- ---
### WP-07 – Interview-Assistent (geplant) ### WP-07 – Interview-Assistent (geplant)
@@ -456,20 +312,13 @@ Entscheidungsunterstützung auf Basis von Wissen, Persönlichkeit und Zielen –
Dialogbasierter Erfassungs-Assistent, der strukturierte Interviews führt und daraus konsistente Markdown-Notizen generiert. Dialogbasierter Erfassungs-Assistent, der strukturierte Interviews führt und daraus konsistente Markdown-Notizen generiert.
**Umfang:** **Umfang:**
- Design von Interview-Flows.
- Design von Interview-Flows (z. B. für Lebensereignisse, Projekte, Werte-Workshops). - Konvertierung von Dialogtranskripten in typisierte Notes.
- Konvertierung von Dialogtranskripten in typisierte Notes (inkl. Typ, Tags, erste Edges).
- Integration mit Vault-Struktur (Ablagepfade, Namenskonventionen).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Niedrig/Mittel - Aufwand: Niedrig/Mittel
- Komplexität: Mittel - Komplexität: Mittel
**DoD (Zielbild):**
- Mindestens ein produktionsnaher Flow (z. B. „Erzähle mir von einem prägenden Ereignis“).
- Automatische Erzeugung von Markdown-Notizen, die vom Importer direkt verarbeitet werden können.
--- ---
### WP-08 – Self-Tuning v1/v2 (geplant) ### WP-08 – Self-Tuning v1/v2 (geplant)
@@ -478,29 +327,16 @@ Dialogbasierter Erfassungs-Assistent, der strukturierte Interviews führt und da
**Status:** 🟡 geplant **Status:** 🟡 geplant
**Ziel:** **Ziel:**
Aufbau eines Self-Tuning-Mechanismus, der auf Basis von Feedback-Daten Vorschläge für Retriever- und Policy-Anpassungen macht. Aufbau eines Self-Tuning-Mechanismus, der auf Basis von Feedback-Daten (WP-04c) Vorschläge für Retriever- und Policy-Anpassungen macht.
**Umfang:** **Umfang:**
- Auswertung der JSONL-Feedback-Daten.
- Auswertung der Feedback-Daten (WP-04c). - Regel-basierte Anpassungs-Vorschläge für `retriever.yaml` und Typ-Prioritäten.
- Regel-basierte Anpassungs-Vorschläge:
- Gewichte in `retriever.yaml`,
- Typ-Prioritäten,
- Edge-Provenance-Gewichte.
- Optionale halbautomatische Übernahme (Freigabe durch Mindmaster).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Hoch - Aufwand: Hoch
- Komplexität: Hoch - Komplexität: Hoch
**DoD (Zielbild):**
- Mindestens ein in der Praxis getesteter Tuning-Zyklus:
- Feedback sammeln,
- Vorschlag generieren,
- Anpassung vornehmen,
- Qualitätsgewinn nachweisen.
--- ---
### WP-09 – Vault-Onboarding & Migration (geplant) ### WP-09 – Vault-Onboarding & Migration (geplant)
@@ -512,24 +348,13 @@ Aufbau eines Self-Tuning-Mechanismus, der auf Basis von Feedback-Daten Vorschlä
Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet integriert werden können – ohne Massenumbau. Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet integriert werden können – ohne Massenumbau.
**Umfang:** **Umfang:**
- Tools zur Analyse des Vault-Status.
- Tools/Guides für: - Empfehlungen für minimale Anpassungen.
- Analyse des Vault-Status (Typen, Edges, Lücken),
- Empfehlungen für minimale Anpassungen (z. B. Typ-Setzung, Basis-Tags),
- optional automatisierte Ergänzung von Properties (mit Freigabe).
- Unterstützung eines „wachsenden Systems“:
- erste Notizen liefern sofort Mehrwert im Retriever,
- später können Typen und Edges ergänzt werden, ohne alte Notizen zu brechen.
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Mittel - Aufwand: Mittel
- Komplexität: Niedrig/Mittel - Komplexität: Niedrig/Mittel
**DoD (Zielbild):**
- Dokumentierter Onboarding-Prozess für Produkt-Vault.
- Mindestens ein erfolgreicher Durchlauf mit deinem realen Vault (Pilot).
--- ---
### WP-10 – Chat-Interface & Writeback (geplant) ### WP-10 – Chat-Interface & Writeback (geplant)
@@ -541,28 +366,13 @@ Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet
Chat-basierter mindnet-Agent, der sowohl Fragen beantwortet als auch neue Notizen erzeugen/aktualisieren kann (Writeback Richtung Vault). Chat-basierter mindnet-Agent, der sowohl Fragen beantwortet als auch neue Notizen erzeugen/aktualisieren kann (Writeback Richtung Vault).
**Umfang:** **Umfang:**
- Chat-Frontend.
- Chat-Frontend (z. B. in deiner bestehenden LLM-Umgebung). - Funktionen für Q&A sowie Vorschlag neuer Notes/Edges.
- Anbindung an:
- `/query` (Retriever),
- MCP-Tools (WP-13),
- Import-/Export-Routinen.
- Funktionen:
- Antworten aus mindnet-Wissen,
- Vorschlag neuer Notes/Edges,
- optionales Schreiben ins Vault (Markdown-Erzeugung, Rewriting nur mit Freigabe).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Hoch - Aufwand: Hoch
- Komplexität: Hoch - Komplexität: Hoch
**DoD (Zielbild):**
- Du kannst im Chat:
- Fragen an dein Wissensnetz stellen,
- neue Gedanken/Erinnerungen erfassen,
- Vorschläge für Ablage & Vernetzung als Markdown-Notizen erhalten.
--- ---
### WP-11 – Knowledge-Builder & Vernetzungs-Assistent (geplant) ### WP-11 – Knowledge-Builder & Vernetzungs-Assistent (geplant)
@@ -573,30 +383,10 @@ Chat-basierter mindnet-Agent, der sowohl Fragen beantwortet als auch neue Notize
**Ziel:** **Ziel:**
Assistent, der manuell erstellte oder importierte Notizen analysiert und Vorschläge für Typen, Edges und Einordnung macht. Assistent, der manuell erstellte oder importierte Notizen analysiert und Vorschläge für Typen, Edges und Einordnung macht.
**Umfang:**
- Analyse neuer/aktualisierter Notes:
- mögliche Typen,
- passende Tags,
- potenzielle Relationen zu bestehenden Notes.
- Vorschläge:
- Inline-Relationen,
- Wikilinks,
- Typ-Zuweisung.
- Optional: Generierung konkreter Patch-Vorschläge für Markdown-Dateien (Diff-basiert).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Hoch - Aufwand: Hoch
- Komplexität: Hoch - Komplexität: Hoch
**DoD (Zielbild):**
- Mindestens ein produktionsnaher Workflow, bei dem ein neuer Eintrag:
- erstellt wird,
- analysiert wird,
- Vernetzungs-Vorschläge liefert,
- und nach Freigabe in den Vault zurückgeschrieben wird.
--- ---
### WP-12 – Knowledge Rewriter (Soft Mode, geplant) ### WP-12 – Knowledge Rewriter (Soft Mode, geplant)
@@ -605,23 +395,12 @@ Assistent, der manuell erstellte oder importierte Notizen analysiert und Vorschl
**Status:** 🟡 geplant **Status:** 🟡 geplant
**Ziel:** **Ziel:**
Optionaler Assistent, der vorhandene Notes „aufräumt“, zusammenfasst oder reorganisiert – ausschließlich mit expliziter Freigabe. :contentReference[oaicite:31]{index=31} Optionaler Assistent, der vorhandene Notes „aufräumt“, zusammenfasst oder reorganisiert – ausschließlich mit expliziter Freigabe.
**Einschränkungen:**
- Änderungen an Markdown-Dateien nur nach Freigabe.
- Kein „silent overwrite“ existierender Inhalte.
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Niedrig/Mittel - Aufwand: Niedrig/Mittel
- Komplexität: Mittel - Komplexität: Mittel
**DoD (Zielbild):**
- Rewriter generiert Vorschläge (neue Versionen) inklusive Diffs.
- Nach Freigabe werden Notes konsistent aktualisiert:
- IDs, Edges und Typen bleiben konsistent oder werden sauber mitaktualisiert.
--- ---
### WP-13 – MCP-Integration & Agenten-Layer (geplant) ### WP-13 – MCP-Integration & Agenten-Layer (geplant)
@@ -630,27 +409,15 @@ Optionaler Assistent, der vorhandene Notes „aufräumt“, zusammenfasst oder r
**Status:** 🟡 geplant **Status:** 🟡 geplant
**Ziel:** **Ziel:**
mindnet als MCP-Server bereitstellen, damit Agenten/LLMs standardisierte Tools nutzen können (z. B. in deiner n8n- und LLM-Umgebung). mindnet als MCP-Server bereitstellen, damit Agenten/LLMs standardisierte Tools nutzen können.
**Umfang:** **Umfang:**
- MCP-Server mit Tools (`mindnet_query`, `mindnet_explain`, etc.).
- MCP-Server mit Tools wie:
- `mindnet_query`,
- `mindnet_subgraph`,
- `mindnet_store_note`,
- `mindnet_explain`.
- Sichere Konfiguration (lokal, authentifiziert, logging-fähig).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Mittel - Aufwand: Mittel
- Komplexität: Mittel - Komplexität: Mittel
**DoD (Zielbild):**
- Lokaler MCP-Server läuft und ist aus einem LLM-Client nutzbar.
- Tools liefern konsistente Ergebnisse (aligned mit FastAPI-Endpoints).
- Sicherheits- und Loggingkonzept dokumentiert.
--- ---
### WP-14 – Review / Refactoring / Dokumentation (geplant) ### WP-14 – Review / Refactoring / Dokumentation (geplant)
@@ -661,25 +428,10 @@ mindnet als MCP-Server bereitstellen, damit Agenten/LLMs standardisierte Tools n
**Ziel:** **Ziel:**
Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritter und Langfrist-Betrieb. Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritter und Langfrist-Betrieb.
**Deliverables (Beispiele):**
- konsolidierte technische Architektur (`mindnet_technical_architecture.md`),
- fachliche Architektur (`mindnet_functional_architecture.md`),
- Identity-Modell (`identity_model.md`),
- API-Spezifikation (`api_spec.md`),
- MCP-Integration (`mcp_integration.md`),
- aktualisiertes Handbuch (`Handbuch.md`).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Mittel - Aufwand: Mittel
- Komplexität: Niedrig/Mittel - Komplexität: Niedrig/Mittel
**DoD (Zielbild):**
- Aktueller Stand ist sauber dokumentiert.
- Wichtige Designentscheidungen sind nachvollziehbar festgehalten.
- Onboarding einer dritten Person (z. B. Entwickler:in) ist mit Dokumentation möglich.
--- ---
## 7. Abhängigkeiten (vereinfacht, aktualisiert) ## 7. Abhängigkeiten (vereinfacht, aktualisiert)
@@ -692,11 +444,9 @@ Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritte
WP03/WP04 → WP13 WP03/WP04 → WP13
Alles → WP14 Alles → WP14
Diese Struktur bleibt gegenüber v2.1 unverändert, ist aber jetzt explizit an den bereits implementierten Stand (WP-03, WP-04a) angepasst.
--- ---
## 8. Laufzeit- & Komplexitätsindikatoren (unverändert, ergänzt) ## 8. Laufzeit- & Komplexitätsindikatoren (aktualisiert)
| WP | Aufwand | Komplexität | | WP | Aufwand | Komplexität |
|-------|----------------|------------------| |-------|----------------|------------------|
@@ -711,9 +461,7 @@ Diese Struktur bleibt gegenüber v2.1 unverändert, ist aber jetzt explizit an d
| WP11 | Hoch | Hoch | | WP11 | Hoch | Hoch |
| WP12 | Niedrig/Mittel | Mittel | | WP12 | Niedrig/Mittel | Mittel |
| WP13 | Mittel | Mittel | | WP13 | Mittel | Mittel |
| WP14 | Mittel | Niedrig/Mittel | :contentReference[oaicite:35]{index=35} | WP14 | Mittel | Niedrig/Mittel |
Für WP01–WP04a gilt: Aufwand/Komplexität wie in v2.1; Status jetzt explizit „abgeschlossen“ mit beschriebenem Funktionsumfang.
--- ---
@@ -725,8 +473,8 @@ Für WP01–WP04a gilt: Aufwand/Komplexität wie in v2.1; Status jetzt explizit
| WP02 | 🟢 | | WP02 | 🟢 |
| WP03 | 🟢 | | WP03 | 🟢 |
| WP04a | 🟢 | | WP04a | 🟢 |
| WP04b | 🟡 | | WP04b | 🟢 |
| WP04c | 🟡 | | WP04c | 🟢 |
| WP05 | 🟡 | | WP05 | 🟡 |
| WP06 | 🟡 | | WP06 | 🟡 |
| WP07 | 🟡 | | WP07 | 🟡 |
@@ -736,37 +484,30 @@ Für WP01–WP04a gilt: Aufwand/Komplexität wie in v2.1; Status jetzt explizit
| WP11 | 🟡 | | WP11 | 🟡 |
| WP12 | 🟡 | | WP12 | 🟡 |
| WP13 | 🟡 | | WP13 | 🟡 |
| WP14 | 🟡 | :contentReference[oaicite:36]{index=36} | WP14 | 🟡 |
--- ---
## 10. Governance & Versionierung ## 10. Governance & Versionierung
- Versionierung über Gitea (Branches, Tags, Releases). - Versionierung über Gitea (Branches, Tags, Releases).
- Jede wesentliche Änderung an Architektur/Schema: - Feature-Branch Workflow mit "Sync First" Strategie.
- eigener Commit, - Jede wesentliche Änderung an Architektur/Schema erhält einen eigenen Commit.
- kurze Doku (z. B. in `CHANGELOG.md` oder Projekt-Notiz).
- Jedes Workpackage erhält ein eigenes Chat-Fenster mit dediziertem Prompt (WP-Hand-Over). - Jedes Workpackage erhält ein eigenes Chat-Fenster mit dediziertem Prompt (WP-Hand-Over).
- Programmleitung verantwortet: - Programmleitung verantwortet Konsistenz und Priorisierung.
- Konsistenz von Fach- und Technikdokumenten,
- Abhängigkeiten und Priorisierung,
- Freigabe von Meilensteinen,
- Sicherstellung, dass Änderungen mit dem langfristigen Ziel (KI-Zwilling) vereinbar sind.
--- ---
## 11. Executive Summary (unverändert, präzisiert) ## 11. Executive Summary
mindnet v2.2 ist so aufgesetzt, dass: mindnet v2.2 ist so aufgesetzt, dass:
- du **schrittweise** Wissen erfassen kannst (Obsidian + Chat + später Interview-Assistent), - du **schrittweise** Wissen erfassen kannst (Obsidian + Chat + später Interview-Assistent),
- die Struktur **mitwächst**, ohne Retro-Massenarbeit im Vault, - die Struktur **mitwächst**, ohne Retro-Massenarbeit im Vault,
- ein **hybrider Retriever** qualitativ hochwertige, erklärbare Antworten liefert, - ein **hybrider Retriever** qualitativ hochwertige, erklärbare Antworten liefert,
- ein **Self-Healing- und Self-Tuning-Mechanismus** vorbereitet ist, der auf Feedback aufsetzt, - ein **Self-Healing- und Self-Tuning-Mechanismus** vorbereitet ist (durch WP-04c Feedback-Daten),
- ein **Persönlichkeitsmodell** und eine **Decision Engine** entstehen, - ein **Persönlichkeitsmodell** und eine **Decision Engine** entstehen,
- langfristig ein **KI-Zwilling** aufgebaut wird, der deine Werte, Erfahrungen und Denkweise spiegelt, - 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. - die technische Architektur (FastAPI, Qdrant, YAML-Policies, MCP-Integration) lokal, nachvollziehbar und erweiterbar bleibt.
Dieser Programmplan bildet die konsolidierte Grundlage (v2.2) für alle weiteren Arbeiten. Dieser Programmplan bildet die konsolidierte Grundlage (v2.2.1) für alle weiteren Arbeiten.
Er integriert die bisherigen Ergebnisse (WP-01 bis WP-04a) und die zusätzlichen Anforderungen aus der späteren Planung (Feedback-basiertes Tuning, wachsendes System, Chat-/Interview-Eingabe, Vault-Writeback) in ein einheitliches, versionierbares Dokument.
+44 -30
View File
@@ -1,6 +1,6 @@
# Mindnet v2.2 – Entwickler-Workflow # Mindnet v2.2 – Entwickler-Workflow
**Datei:** `DEV_WORKFLOW.md` **Datei:** `DEV_WORKFLOW.md`
**Stand:** 2025-12-07 **Stand:** 2025-12-07 (Aktualisiert nach WP-04b)
Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server). Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
@@ -27,29 +27,26 @@ Hier erstellst du die neue Funktion in einer sicheren Umgebung.
* Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. `main`). * Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. `main`).
2. **Branch erstellen (WICHTIG):** 2. **Branch erstellen (WICHTIG):**
* Klicke unten links auf den Branch-Namen (z.B. `main`). * Klicke unten links auf den Branch-Namen.
* Wähle im Menü oben `+ Create new branch...`. * Wähle `+ Create new branch...`.
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`). * Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
* Drücke **Enter**. * Drücke **Enter**.
3. **Sicherheits-Check:** 3. **Sicherheits-Check:**
* Schau unten links: Steht dort jetzt `feature/wp04b-explanation`? * Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!**
* **Nur wenn dort dein Feature-Branch steht, darfst du Code ändern!** Alles, was du jetzt speicherst, landet in diesem Branch.
4. **Coden:** 4. **Coden:**
* Nimm deine Änderungen vor. * Nimm deine Änderungen vor.
5. **Sichern & Hochladen:** 5. **Sichern & Hochladen:**
* Klicke links auf das **Source Control** Icon (Gabel-Symbol). * **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**.
* Gib eine Nachricht ein: "feat: Add explanation layer logic". * **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
* Klicke auf **Commit**.
* Klicke auf **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
--- ---
### Phase 2: Testen (Beelink / `mindnet_dev`) ### Phase 2: Testen (Beelink / `mindnet_dev`)
Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produktion zu stören. Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.
1. **Einloggen:** 1. **Einloggen:**
`ssh user@<BEELINK-IP>` `ssh user@<BEELINK-IP>`
@@ -60,34 +57,34 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produ
3. **Code holen:** 3. **Code holen:**
```bash ```bash
git fetch git fetch
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
git checkout feature/wp04b-explanation git checkout feature/wp04b-explanation
git pull git pull
``` ```
4. **Umgebung aktivieren (Venv):** 4. **Umgebung vorbereiten:**
Damit Python die installierten Bibliotheken findet, musst du das Virtual Environment aktivieren:
```bash ```bash
source .venv/bin/activate source .venv/bin/activate
pip install -r requirements.txt # Nur nötig bei neuen Paketen
``` ```
*(Dein Prompt sollte jetzt `(.venv) user@...` zeigen)*
5. **Abhängigkeiten prüfen:** 5. **Test-Server neustarten (WICHTIG):**
*(Nur nötig, wenn du neue Libraries in `requirements.txt` eingetragen hast)* Falls noch ein alter Prozess läuft, musst du ihn beenden, damit der neue Code geladen wird.
* Drücke `Strg + C` falls der Server noch im Vordergrund läuft.
* Oder nutze `pkill -f "uvicorn app.main:app"` um Hintergrunde-Prozesse zu stoppen.
Starten auf **Port 8002**:
```bash ```bash
pip install -r requirements.txt uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
``` ```
6. **Test-Server starten:** 6. **Validieren:**
**WICHTIG:** Nutze Port **8002** und das Dev-Prefix! Führe deine Tests in einem **zweiten Terminal** aus:
Stelle sicher, dass in `~/mindnet_dev/.env` steht: `COLLECTION_PREFIX="mindnet_dev"`.
```bash ```bash
uvicorn app.main:app --host 0.0.0.0 --port 8002 # Beispiel für Smoke-Test gegen Dev-Port
python3 tests/test_explanation_smoke.py --url http://localhost:8002/query
``` ```
7. **Testen:**
Prüfe deine Änderung (z.B. Browser auf `http://<BEELINK-IP>:8002/docs` oder Smoke-Test Skript).
--- ---
### Phase 3: Release (Gitea / Raspberry Pi) ### Phase 3: Release (Gitea / Raspberry Pi)
@@ -95,9 +92,8 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produ
Wenn der Test auf Port 8002 erfolgreich war: Wenn der Test auf Port 8002 erfolgreich war:
1. Öffne Gitea im Browser. 1. Öffne Gitea im Browser.
2. Du solltest einen Hinweis sehen "feature/... had recent pushes". 2. Erstelle einen **Pull Request** (Dein Branch -> `main`).
3. Erstelle einen **Pull Request** (Dein Branch -> `main`). 3. **Merge** den Pull Request.
4. **Merge** den Pull Request.
--- ---
@@ -117,6 +113,24 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001).
--- ---
### 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/wp04b-explanation
```
3. **VS Code:**
* Auf `main` wechseln.
* `F1` -> `Git: Delete Branch` -> Branch auswählen.
---
## 3. Cheat Sheet: Die wichtigsten Befehle ## 3. Cheat Sheet: Die wichtigsten Befehle
| Wo? | Befehl | Was tut es? | | Wo? | Befehl | Was tut es? |
@@ -125,16 +139,16 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001).
| **VS Code** | `Sync Changes` | Lädt Code zu Gitea hoch. | | **VS Code** | `Sync Changes` | Lädt Code zu Gitea hoch. |
| **Beelink** | `cd ~/mindnet_dev` | Gehe in den Test-Ordner. | | **Beelink** | `cd ~/mindnet_dev` | Gehe in den Test-Ordner. |
| **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** | | **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
| **Beelink** | `git fetch` | "Gibt es neue Branches auf Gitea?" | | **Beelink** | `git fetch` | Aktualisiert die Liste der Remote-Branches. |
| **Beelink** | `git branch -r` | Zeigt alle Branches auf dem Server an. |
| **Beelink** | `git checkout <name>` | Wechsle auf einen anderen Branch. | | **Beelink** | `git checkout <name>` | Wechsle auf einen anderen Branch. |
| **Beelink** | `git pull` | Hol den neuesten Stand des aktuellen Branches. |
| **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). | | **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |
--- ---
## 4. Sicherheitsregeln ## 4. Sicherheitsregeln
1. **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren oder `git checkout` machen. Dieser Ordner bleibt immer auf `main`. 1. **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren. Dieser Ordner bleibt immer auf `main`.
2. **Niemals** beide Umgebungen auf denselben `COLLECTION_PREFIX` zeigen lassen. 2. **Niemals** beide Umgebungen auf denselben `COLLECTION_PREFIX` zeigen lassen.
* Prod `.env`: `COLLECTION_PREFIX="mindnet"` * Prod `.env`: `COLLECTION_PREFIX="mindnet"`
* Dev `.env`: `COLLECTION_PREFIX="mindnet_dev"` * Dev `.env`: `COLLECTION_PREFIX="mindnet_dev"`