Compare commits

...
Author SHA1 Message Date
Lars 548c503e7c Merge pull request 'WP25b' (#21) from WP25b into main
Deploy mindnet to llm-node / deploy (push) Successful in 5s
Reviewed-on: #21
2026-01-03 15:12:58 +01:00
Lars 277444ec0a Enhance Decision Engine configuration: Add 'expert_for' setting to edge_boosts in decision_engine.yaml to improve strategy determination and flexibility.
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2026-01-03 15:09:31 +01:00
Lars 62a00d1ac3 Update documentation and technical references for Mindnet v3.1.1: Revise versioning across all documents to reflect the latest updates, including the integration of Lazy-Prompt-Orchestration and enhancements in AI model capabilities. Update context descriptions to clarify new features and improvements in prompt management, ingestion validation, and decision engine processes. 2026-01-03 09:56:49 +01:00
Lars 8505538b34 Refactor ingestion validation and decision engine error handling: Differentiate between transient and permanent validation errors in ingestion validation to improve data integrity. Enhance decision engine configuration loading with schema validation and error handling for missing keys and YAML syntax errors. Update fallback synthesis prompt handling in LLMService for improved error recovery. Add new fallback synthesis prompts to prompts.yaml for better context-based responses. 2026-01-02 22:09:16 +01:00
Lars a9d0874fe9 Enhance prompt retrieval in LLMService: Implement detailed trace-logging for prompt lookup hierarchy, improving traceability of model-specific, provider, and global fallback matches. This update refines the logging mechanism to provide clearer insights during prompt resolution. 2026-01-02 21:47:47 +01:00
Lars 1563ebbdf9 Update Decision Engine to version 1.3.2: Implement ultra-robust intent parsing using regex, restore prepend_instruction logic, and enhance logging for configuration loading. Improve fallback mechanisms for response generation to ensure reliability. 2026-01-02 21:42:09 +01:00
Lars 38fac89f73 Update Decision Engine for WP-25b: Enhance intent processing with robust intent cleaning and lazy loading. Improve strategy determination by validating against known strategies and streamline response generation. Bump version to 1.3.1 to reflect these optimizations. 2026-01-02 21:35:02 +01:00
Lars 7026fc4fed Update components for WP-25b: Implement Lazy-Prompt-Orchestration across ingestion, decision engine, chat interface, and LLM service. Enhance prompt management with hierarchical model support and streamline response generation by removing manual formatting. Bump versions to reflect new features and optimizations. 2026-01-02 20:43:31 +01:00
Lars d41da670fc Merge pull request 'WP25a' (#20) from WP25a into main
Deploy mindnet to llm-node / deploy (push) Successful in 3s
Reviewed-on: #20
2026-01-02 13:55:09 +01:00
Lars 5541ceb13d Update LLM profiles in llm_profiles.yaml: Change models for 'synthesis_pro', 'synthesis_backup', and 'tech_expert' profiles to enhance performance and capabilities, reflecting the latest advancements in AI model offerings. 2026-01-02 13:46:50 +01:00
Lars ac26cc4940 Update documentation and technical references for Mindnet v3.0.0: Revise glossary, AI personality concepts, chat backend, configuration, ingestion pipeline, and admin operations to reflect the integration of Mixture of Experts (MoE) architecture and associated features. Enhance clarity on profile-driven orchestration, fallback mechanisms, and pre-synthesis compression across components. 2026-01-02 11:34:37 +01:00
Lars 9b906bbabf Update FastAPI application and related services for WP-25a: Enhance lifespan management with Mixture of Experts (MoE) integrity checks, improve logging and error handling in LLMService, and integrate profile-driven orchestration across components. Bump versions for main application, ingestion services, and LLM profiles to reflect new features and optimizations. 2026-01-02 08:57:29 +01:00
Lars 9a98093e70 Enhance Decision Engine configuration: Add 'router_profile' setting to decision_engine.yaml and update the DecisionEngine class to utilize this profile when generating responses, improving flexibility in strategy determination. 2026-01-02 07:45:34 +01:00
Lars de05784428 Update LLM profiles in llm_profiles.yaml: Change model for 'compression_fast' and 'synthesis_pro' profiles to 'mistralai/mistral-7b-instruct:free' and adjust provider for 'synthesis_pro' to 'openrouter' for improved performance. 2026-01-02 07:31:09 +01:00
Lars f62983b08f Enhance logging in LLMService: Update log messages for MoE dispatch and default provider usage, and add detailed logging before OpenRouter calls for improved traceability and debugging. 2026-01-02 07:26:24 +01:00
Lars d0eae8e43c Update Decision Engine and related components for WP-25a: Bump version to 1.2.0, enhance multi-stream retrieval with pre-synthesis compression, and integrate Mixture of Experts (MoE) profile support. Refactor chat interface to utilize new compression logic and llm_profiles for improved synthesis. Maintain compatibility with existing methods and ensure robust error handling across services. 2026-01-02 07:04:43 +01:00
Lars 3d2f3d12d9 Merge pull request 'WP25' (#19) from WP25 into main
Deploy mindnet to llm-node / deploy (push) Successful in 5s
Reviewed-on: #19
2026-01-01 20:26:05 +01:00
Lars 0d2469f8fa WP25-v3.0.0-Dokumentation 2026-01-01 20:24:09 +01:00
Lars 124849c580 Update decision_engine.yaml for WP-25: Bump version to 3.1.6, enhance definitions with stricter type usage from types.yaml, and refine strategy descriptions. Introduce new trigger keywords for improved intent classification and ensure compatibility with multi-stream retrieval strategies. Add clarifications for emotional reflection and technical support strategies. 2026-01-01 13:10:42 +01:00
Lars ea38743a2a Update Decision Engine and DTOs for WP-25: Bump version to 1.0.3 and 0.7.1 respectively. Introduce stream tracing support by adding 'stream_origin' to QueryHit model. Enhance robustness with pre-initialization of stream variables and improve logging for unknown strategies. Refactor prompts for clarity and consistency in multi-stream synthesis. 2026-01-01 12:38:32 +01:00
Lars 5ab01c5150 Update decision_engine.yaml and prompts.yaml for WP-25: Bump version to 3.1.5, enhance stream definitions with stricter type usage from types.yaml, and refine strategy descriptions for clarity. Introduce new trigger keywords for improved intent classification and ensure compatibility with multi-stream retrieval strategies. 2026-01-01 09:12:31 +01:00
Lars ed3f3e5588 Update Decision Engine for WP-25: Bump version to 1.0.2, enhance robustness by pre-initializing stream variables to prevent KeyErrors, and fix template mismatches in strategy definitions. Ensure compatibility with updated YAML configuration for multi-stream retrieval strategies. 2026-01-01 08:51:33 +01:00
Lars bb6959a090 Update LLMService for WP-25: Enhance stability with improved response handling, including safeguards against empty responses and adjustments for short input validations. Maintain compatibility with previous logic for rate limits and retries. Version bump to 3.4.2. 2026-01-01 08:31:15 +01:00
Lars d49d509451 Initialize logging setup in main application prior to app creation for improved error tracking and management. 2026-01-01 08:09:20 +01:00
Lars 008167268f Update main application and services for WP-25 release, introducing Agentic Multi-Stream RAG capabilities. Enhance lifespan management, global error handling, and integrate LLMService with DecisionEngine for improved retrieval and synthesis. Update dependencies and versioning across modules, ensuring compatibility with new multi-stream architecture. Refactor chat router to support new intent classification and retrieval strategies, while maintaining stability and performance improvements. 2026-01-01 07:52:41 +01:00
Lars 67d7154328 Merge pull request 'WP15c' (#18) from WP15c into main
Deploy mindnet to llm-node / deploy (push) Successful in 4s
Reviewed-on: #18
2025-12-31 16:56:36 +01:00
Lars 4de9a4f649 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. 2025-12-31 16:55:12 +01:00
Lars d35bdc64b9 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. 2025-12-30 21:47:18 +01:00
Lars 3a768be488 docs/06_Roadmap/06_handover_prompts.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-30 16:33:29 +01:00
Lars 1965c984f4 docs/06_Roadmap/06_handover_prompts.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-30 16:32:06 +01:00
Lars e3e1700de5 docs/06_Roadmap/06_handover_prompts.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-30 16:31:33 +01:00
Lars f05d766b64 docs/06_Roadmap/06_handover_prompts.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-30 16:30:19 +01:00
Lars 58e414041a docs/06_Roadmap/06_handover_prompts.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-30 16:26:38 +01:00
Lars cd5056d4c9 Merge pull request 'WP4d' (#16) from WP4d into main
Deploy mindnet to llm-node / deploy (push) Successful in 4s
Reviewed-on: #16
2025-12-30 12:25:33 +01:00
Lars 39fb821481 WP4d - branch merger Comment & Release Note 2025-12-30 12:24:20 +01:00
Lars beb87a8c43 Update documentation to version 2.9.1, introducing support for section-based links and multigraph functionality. Enhance glossary, user manual, and technical references to reflect new deep-linking capabilities and edge structure adjustments. Ensure proper migration instructions for users transitioning to the new version. 2025-12-30 12:16:58 +01:00
Lars 4327fc939c zrück zur Vorversion zum Test der LLM checks 2025-12-30 09:40:30 +01:00
Lars ef1046c6f5 Enhance callout relation extraction by ensuring correct termination on new headers. Update regex for simple kinds to support hyphens. Refactor block processing logic for improved clarity and functionality. 2025-12-30 09:26:38 +01:00
Lars ef8cf719f2 Update ingestion processor to version 2.13.12, synchronizing profile resolution with registry defaults. Refactor profile retrieval logic to utilize the profile determined in make_note_payload, ensuring consistency in chunk configuration. 2025-12-30 09:11:55 +01:00
Lars 6aa6b32a6c Update chunking system to version 3.9.9, synchronizing parameters with the orchestrator and enhancing edge detection. Implement robust parsing to prevent duplicate edges in section propagation. Adjust comments for clarity and consistency across the codebase. 2025-12-30 08:40:19 +01:00
Lars 33dff04d47 Fix v3.3.5: Prevent duplicate Wikilink targets in text by checking for existing references before injecting section edges. Update comments for clarity and maintain consistency in the code structure. 2025-12-30 08:22:17 +01:00
Lars 65d697b7be Aktualisierung der atomaren Sektions-Chunking-Strategie auf Version 3.9.8 mit verbesserten Implementierungen des 'Pack-and-Carry-Over' Verfahrens. Einführung von Look-Ahead zur strikten Einhaltung von Sektionsgrenzen und Vermeidung redundanter Kanten-Injektionen. Anpassungen an der Chunk-Erstellung und Optimierung der Handhabung von leeren Überschriften. 2025-12-30 07:54:54 +01:00
Lars 06fc42ed37 Aktualisierung des Chunking-Parsers zur Einführung der Funktion parse_edges_robust zur Extraktion von Kanten-Kandidaten aus Wikilinks und Callouts. Verbesserung der Satzverarbeitung durch die Implementierung der Funktion split_sentences. Aktualisierung der Sektions-Chunking-Strategie auf Version 3.9.6 mit optimierter Handhabung von leeren Überschriften und Carry-Over Logik zur besseren Chunk-Erstellung. 2025-12-30 07:44:30 +01:00
Lars 3c5c567077 Aktualisierung der atomaren Sektions-Chunking-Strategie auf Version 3.9.5 mit Implementierung des 'Pack-and-Carry-Over' Verfahrens. Einführung neuer Konfigurationsoptionen für Smart-Edge und strikte Überschriftenteilung. Verbesserte Handhabung von leeren Überschriften und Anpassungen an der Warteschlangen-Verarbeitung zur Optimierung der Chunk-Erstellung. 2025-12-30 07:41:30 +01:00
Lars 8f65e550c8 Optimierung des Chunking-Parsers zur Unterstützung atomarer Blöcke und Verbesserung der Satzverarbeitung. Aktualisierung der Sektions-Chunking-Strategie auf Version 3.9.0 mit regelkonformer Implementierung und Anpassungen an der Warteschlangen-Verarbeitung für Carry-Over. Verbesserte Handhabung von Überschriften und Metadaten zur Gewährleistung der strukturellen Integrität. 2025-12-29 22:16:12 +01:00
Lars 6b83879741 Aktualisierung des Chunking-Parsers zur Verbesserung der Satzverarbeitung und Blocktrennung. Einführung des 'Pack-and-Carry-Over' Verfahrens in der Sektions-Chunking-Strategie zur Optimierung der Handhabung von großen Sektionen und Gewährleistung der Sektionsintegrität. Anpassungen an der Token-Schätzung und Verbesserung der Metadatenverarbeitung. 2025-12-29 22:04:23 +01:00
Lars be265e9cc0 Verbesserung des Chunking-Parsers zur Unterstützung atomarer Blöcke und Gewährleistung der strukturellen Integrität von Callouts. Aktualisierung der Beschreibung und Optimierung der Satz- und Blockverarbeitung, einschließlich präziserer Handhabung von H1-Überschriften und Trennern. 2025-12-29 21:48:54 +01:00
Lars 680c36ab59 Aktualisierung des Chunking-Parsers zur Verbesserung der Blockverarbeitung und Beschreibung. Anpassungen an der atomaren Sektions-Chunking-Strategie mit optimierter Token-Schätzung und neuen Hilfsfunktionen zur besseren Handhabung von großen Sektionen. Einführung einer präziseren Schätzung für deutsche Texte und Anpassungen an der Logik zur Handhabung von Sektionen. 2025-12-29 21:45:14 +01:00
Lars 96b4f65cd1 Aktualisierung des Chunking-Parsers zur Verbesserung der Blockverarbeitung und Beschreibung. Anpassungen an der atomaren Sektions-Chunking-Strategie mit optimierter Token-Schätzung und neuen Hilfsfunktionen zur besseren Handhabung von großen Sektionen. 2025-12-29 21:37:11 +01:00
Lars b1a897e51c Verbesserung des Chunking-Parsers zur Unterstützung aller Überschriften (H1-H6) und Optimierung der Block-Trennung für atomares Sektions-Chunking. Aktualisierung der Sektions-Chunking-Strategie mit striktem Look-Ahead und präziserer Token-Schätzung für eine verbesserte Handhabung von großen Blöcken. 2025-12-29 21:26:05 +01:00
Lars e5a34efee9 Verbesserung des Chunking-Parsers zur Gewährleistung der Integrität von Callouts und Listen sowie Anpassungen an der Blockverarbeitung. Aktualisierung der atomaren Sektions-Chunking-Strategie mit Block-Aware-Flushing und optimierter Token-Schätzung für eine präzisere Handhabung von großen Blöcken. 2025-12-29 21:15:03 +01:00
Lars f9ac4e4dbf Verbesserung der atomaren Sektions-Chunking-Strategie durch Einführung strikter Look-Ahead-Logik und präventiven Flush zur Gewährleistung von Sektionsgrenzen. Anpassungen an der Token-Schätzung und Umbenennung von Funktionen zur besseren Lesbarkeit. 2025-12-29 21:05:42 +01:00
Lars 1b40e29f40 Optimierung des Chunking-Parsers zur Unterstützung atomares Chunking und verbesserte Block-Trennung. Anpassungen an der Sektions-Chunking-Strategie zur Wahrung von Sektionsgrenzen und Vermeidung von Überhängen. 2025-12-29 20:57:07 +01:00
Lars 7eba1fb487 Aktualisierung des Chunking-Parsers zur Unterstützung aller Überschriften im Stream und Verbesserung der Metadatenverarbeitung. Anpassungen an der atomaren Sektions-Chunking-Strategie zur besseren Handhabung von Blockinhalten und Token-Schätzungen. 2025-12-29 20:45:04 +01:00
Lars 838083b909 Verbesserung des Chunking-Parsers zur Unterstützung von H1-Überschriften und Anpassung der Metadatenlogik. Implementierung einer atomaren Sektions-Chunking-Strategie, die Überschriften und deren Inhalte zusammenhält. 2025-12-29 20:33:43 +01:00
Lars 8f5eb36b5f neuer Chunking parser, der Headings mitführt und nicht mitten im Abschnitt schneidet 2025-12-29 20:16:23 +01:00
Lars b7d1bcce3d Rücksprung zur Vorwersion, in der 2 Kantentypen angelegt wurden 2025-12-29 18:04:14 +01:00
Lars 03d3173ca6 neu deduplizierung für callout-edges 2025-12-29 12:42:26 +01:00
Lars 38a61d7b50 Fix: Semantische Deduplizierung in graph_derive_edges.py 2025-12-29 12:21:57 +01:00
Lars 0a429e1f7b anpassungen Kantenvergeleich 2025-12-29 11:45:25 +01:00
Lars 857ba953e3 bug fix 2025-12-29 11:00:00 +01:00
Lars e180018c99 Anpassung gui 2025-12-29 10:31:51 +01:00
Lars ac9956bf00 Index und Anlage neues Feld in qdrant 2025-12-29 10:16:51 +01:00
Lars 62b5a8bf65 Anpassung payload für neues Feld in edges 2025-12-29 08:40:05 +01:00
Lars 303efefcb7 bug fix 2025-12-29 08:19:40 +01:00
Lars feeb7c2d92 Initial WP4d 2025-12-29 07:58:20 +01:00
Lars ea9a54421a ui_fraph.old Version 2025-12-29 07:51:07 +01:00
Lars fdf99b2bb0 bug fix
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 18:53:11 +01:00
Lars c7cd641f89 bug fix
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 18:51:44 +01:00
Lars 18b90c8df3 bug fix
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 18:16:29 +01:00
Lars 8d3bc1c2e2 next try
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 12:00:31 +01:00
Lars 079d988034 bug fix
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-28 11:57:49 +01:00
Lars aa9d388337 ui_update
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 11:54:44 +01:00
Lars 92bd3d9a47 bug fix
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-28 11:52:49 +01:00
Lars 53058d1504 bug fix
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 11:49:41 +01:00
Lars 3fe8463a03 bug fix
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 11:44:04 +01:00
Lars 5c4ce5d727 neuer test
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-28 11:41:47 +01:00
Lars 459193e7b1 test ui
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 11:38:51 +01:00
Lars 98f21323fb bug fix
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-28 11:35:18 +01:00
Lars 515248d438 kanten mit #Abschnitt finden
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 11:30:22 +01:00
Lars b0c69ad3e0 UI test
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 11:23:46 +01:00
Lars c5f29ab4ae Erweiterung der Kanten um Abschnittsinformationen
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-28 11:20:30 +01:00
Lars 876ee898d8 Ui_Update_cytos
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 11:15:11 +01:00
Lars e93bab6ea7 Fassadenauflösung unter app/core
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-28 11:04:40 +01:00
Lars 5225090490 Dokumentationsaupdate
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-28 10:56:34 +01:00
Lars e9532e8878 script_Überprüfung und Kommentarheader
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-28 10:40:28 +01:00
128 changed files with 10679 additions and 2020 deletions

No files matched your search

+47 -25
View File
@@ -1,6 +1,8 @@
"""
FILE: app/core/chunking/chunking_parser.py
DESCRIPTION: Zerlegt Markdown in Blöcke und extrahiert Kanten-Strings.
DESCRIPTION: Zerlegt Markdown in logische Einheiten (RawBlocks).
Hält alle Überschriftenebenen (H1-H6) im Stream.
Stellt die Funktion parse_edges_robust zur Verfügung.
"""
import re
from typing import List, Tuple, Set
@@ -11,69 +13,86 @@ _WS = re.compile(r'\s+')
_SENT_SPLIT = re.compile(r'(?<=[.!?])\s+(?=[A-ZÄÖÜ0-9„(])')
def split_sentences(text: str) -> list[str]:
"""Teilt Text in Sätze auf."""
"""Teilt Text in Sätze auf unter Berücksichtigung deutscher Interpunktion."""
text = _WS.sub(' ', text.strip())
if not text: return []
# Splittet bei Punkt, Ausrufezeichen oder Fragezeichen, gefolgt von Leerzeichen und Großbuchstabe
return [p.strip() for p in _SENT_SPLIT.split(text) if p.strip()]
def parse_blocks(md_text: str) -> Tuple[List[RawBlock], str]:
"""Zerlegt Text in logische Einheiten."""
"""Zerlegt Text in logische Einheiten (RawBlocks), inklusive H1-H6."""
blocks = []
h1_title = "Dokument"; section_path = "/"; current_h2 = None
h1_title = "Dokument"
section_path = "/"
current_section_title = None
# Frontmatter entfernen
fm, text_without_fm = extract_frontmatter_from_text(md_text)
# H1 für Note-Titel extrahieren (Metadaten-Zweck)
h1_match = re.search(r'^#\s+(.*)', text_without_fm, re.MULTILINE)
if h1_match: h1_title = h1_match.group(1).strip()
if h1_match:
h1_title = h1_match.group(1).strip()
lines = text_without_fm.split('\n')
buffer = []
for line in lines:
stripped = line.strip()
# H1 ignorieren (ist Doc Title)
if stripped.startswith('# '):
continue
# Generische Heading-Erkennung (H2 bis H6) für flexible Split-Levels
heading_match = re.match(r'^(#{2,6})\s+(.*)', stripped)
# Heading-Erkennung (H1 bis H6)
heading_match = re.match(r'^(#{1,6})\s+(.*)', stripped)
if heading_match:
# Buffer leeren (vorherigen Text abschließen)
# Vorherigen Text-Block abschließen
if buffer:
content = "\n".join(buffer).strip()
if content: blocks.append(RawBlock("paragraph", content, None, section_path, current_h2))
if content:
blocks.append(RawBlock("paragraph", content, None, section_path, current_section_title))
buffer = []
level = len(heading_match.group(1))
title = heading_match.group(2).strip()
# Pfad-Logik: H2 setzt den Haupt-Pfad
if level == 2:
current_h2 = title
section_path = f"/{current_h2}"
# Bei H3+ bleibt der section_path beim Parent, aber das Level wird korrekt gesetzt
# Pfad- und Titel-Update für die Metadaten der folgenden Blöcke
if level == 1:
current_section_title = title; section_path = "/"
elif level == 2:
current_section_title = title; section_path = f"/{current_section_title}"
blocks.append(RawBlock("heading", stripped, level, section_path, current_h2))
elif not stripped:
# Die Überschrift selbst als regulären Block hinzufügen
blocks.append(RawBlock("heading", stripped, level, section_path, current_section_title))
continue
# Trenner (---) oder Leerzeilen beenden Blöcke, außer innerhalb von Callouts
if (not stripped or stripped == "---") and not line.startswith('>'):
if buffer:
content = "\n".join(buffer).strip()
if content: blocks.append(RawBlock("paragraph", content, None, section_path, current_h2))
if content:
blocks.append(RawBlock("paragraph", content, None, section_path, current_section_title))
buffer = []
if stripped == "---":
blocks.append(RawBlock("separator", "---", None, section_path, current_section_title))
else:
buffer.append(line)
if buffer:
content = "\n".join(buffer).strip()
if content: blocks.append(RawBlock("paragraph", content, None, section_path, current_h2))
if content:
blocks.append(RawBlock("paragraph", content, None, section_path, current_section_title))
return blocks, h1_title
def parse_edges_robust(text: str) -> Set[str]:
"""Extrahiert Kanten-Kandidaten (Wikilinks, Callouts)."""
"""Extrahiert Kanten-Kandidaten aus Wikilinks und Callouts."""
found_edges = set()
# 1. Wikilinks [[rel:kind|target]]
inlines = re.findall(r'\[\[rel:([^\|\]]+)\|?([^\]]*)\]\]', text)
for kind, target in inlines:
k = kind.strip().lower()
t = target.strip()
if k and t: found_edges.add(f"{k}:{t}")
# 2. Callout Edges > [!edge] kind
lines = text.split('\n')
current_edge_type = None
for line in lines:
@@ -81,13 +100,16 @@ def parse_edges_robust(text: str) -> Set[str]:
callout_match = re.match(r'>\s*\[!edge\]\s*([^:\s]+)', stripped)
if callout_match:
current_edge_type = callout_match.group(1).strip().lower()
# Links in der gleichen Zeile des Callouts
links = re.findall(r'\[\[([^\]]+)\]\]', stripped)
for l in links:
if "rel:" not in l: found_edges.add(f"{current_edge_type}:{l}")
continue
# Links in Folgezeilen des Callouts
if current_edge_type and stripped.startswith('>'):
links = re.findall(r'\[\[([^\]]+)\]\]', stripped)
for l in links:
if "rel:" not in l: found_edges.add(f"{current_edge_type}:{l}")
elif not stripped.startswith('>'): current_edge_type = None
elif not stripped.startswith('>'):
current_edge_type = None
return found_edges
+13 -7
View File
@@ -1,7 +1,8 @@
"""
FILE: app/core/chunking/chunking_processor.py
DESCRIPTION: Der zentrale Orchestrator für das Chunking-System.
AUDIT v3.3.3: Wiederherstellung der "Gold-Standard" Qualität.
AUDIT v3.3.4: Wiederherstellung der "Gold-Standard" Qualität.
- Fix: Synchronisierung der Parameter (context_prefix) für alle Strategien.
- Integriert physikalische Kanten-Injektion (Propagierung).
- Stellt H1-Kontext-Fenster sicher.
- Baut den Candidate-Pool für die WP-15b Ingestion auf.
@@ -30,16 +31,19 @@ async def assemble_chunks(note_id: str, md_text: str, note_type: str, config: Op
fm, body_text = extract_frontmatter_from_text(md_text)
blocks, doc_title = parse_blocks(md_text)
# Vorbereitung des H1-Präfix für die Embedding-Fenster
# Vorbereitung des H1-Präfix für die Embedding-Fenster (Breadcrumbs)
h1_prefix = f"# {doc_title}" if doc_title else ""
# 2. Anwendung der Splitting-Strategie
# Wir übergeben den Dokument-Titel/Präfix für die Window-Bildung.
# Alle Strategien nutzen nun einheitlich context_prefix für die Window-Bildung.
if config.get("strategy") == "by_heading":
chunks = await asyncio.to_thread(strategy_by_heading, blocks, config, note_id, doc_title)
chunks = await asyncio.to_thread(
strategy_by_heading, blocks, config, note_id, context_prefix=h1_prefix
)
else:
# sliding_window nutzt nun den context_prefix für das Window-Feld.
chunks = await asyncio.to_thread(strategy_sliding_window, blocks, config, note_id, context_prefix=h1_prefix)
chunks = await asyncio.to_thread(
strategy_sliding_window, blocks, config, note_id, context_prefix=h1_prefix
)
if not chunks:
return []
@@ -52,6 +56,7 @@ async def assemble_chunks(note_id: str, md_text: str, note_type: str, config: Op
# Zuerst die explizit im Text vorhandenen Kanten sammeln.
for ch in chunks:
# Wir extrahieren aus dem bereits (durch Propagation) angereicherten Text.
# ch.candidate_pool wird im Modell-Konstruktor als leere Liste initialisiert.
for e_str in parse_edges_robust(ch.text):
parts = e_str.split(':', 1)
if len(parts) == 2:
@@ -71,7 +76,7 @@ async def assemble_chunks(note_id: str, md_text: str, note_type: str, config: Op
parts = e_str.split(':', 1)
if len(parts) == 2:
k, t = parts
# Diese Kanten werden als "Global Pool" markiert für die spätere KI-Prüfung.
# Diese Kanten werden als "global_pool" markiert für die spätere KI-Prüfung.
for ch in chunks:
ch.candidate_pool.append({"kind": k, "to": t, "provenance": "global_pool"})
@@ -80,6 +85,7 @@ async def assemble_chunks(note_id: str, md_text: str, note_type: str, config: Op
seen = set()
unique = []
for c in ch.candidate_pool:
# Eindeutigkeit über Typ, Ziel und Herkunft (Provenance)
key = (c["kind"], c["to"], c["provenance"])
if key not in seen:
seen.add(key)
+17 -11
View File
@@ -1,9 +1,8 @@
"""
FILE: app/core/chunking/chunking_propagation.py
DESCRIPTION: Injiziert Sektions-Kanten physisch in den Text (Embedding-Enrichment).
Stellt die "Gold-Standard"-Qualität von v3.1.0 wieder her.
VERSION: 3.3.1
STATUS: Active
Fix v3.3.6: Nutzt robustes Parsing zur Erkennung vorhandener Kanten,
um Dopplungen direkt hinter [!edge] Callouts format-agnostisch zu verhindern.
"""
from typing import List, Dict, Set
from .chunking_models import Chunk
@@ -12,7 +11,7 @@ from .chunking_parser import parse_edges_robust
def propagate_section_edges(chunks: List[Chunk]) -> List[Chunk]:
"""
Sammelt Kanten pro Sektion und schreibt sie hart in den Text und das Window.
Dies ist essenziell für die Vektorisierung der Beziehungen.
Verhindert Dopplungen, wenn Kanten bereits via [!edge] Callout vorhanden sind.
"""
# 1. Sammeln: Alle expliziten Kanten pro Sektions-Pfad aggregieren
section_map: Dict[str, Set[str]] = {} # path -> set(kind:target)
@@ -36,21 +35,28 @@ def propagate_section_edges(chunks: List[Chunk]) -> List[Chunk]:
if not edges_to_add:
continue
# Vorhandene Kanten (Typ:Ziel) in DIESEM Chunk ermitteln,
# um Dopplungen (z.B. durch Callouts) zu vermeiden.
existing_edges = parse_edges_robust(ch.text)
injections = []
for e_str in edges_to_add:
# Sortierung für deterministische Ergebnisse
for e_str in sorted(list(edges_to_add)):
# Wenn die Kante (Typ + Ziel) bereits vorhanden ist (egal welches Format),
# überspringen wir die Injektion für diesen Chunk.
if e_str in existing_edges:
continue
kind, target = e_str.split(':', 1)
# Nur injizieren, wenn die Kante nicht bereits im Text steht
token = f"[[rel:{kind}|{target}]]"
if token not in ch.text:
injections.append(token)
injections.append(f"[[rel:{kind}|{target}]]")
if injections:
# Physische Anreicherung (Der v3.1.0 Qualitäts-Fix)
# Physische Anreicherung
# Triple-Newline für saubere Trennung im Embedding-Fenster
block = "\n\n\n" + " ".join(injections)
ch.text += block
# ENTSCHEIDEND: Auch ins Window schreiben, da Qdrant hier sucht!
# Auch ins Window schreiben, da Qdrant hier sucht!
if ch.window:
ch.window += block
else:
+135 -111
View File
@@ -1,142 +1,166 @@
"""
FILE: app/core/chunking/chunking_strategies.py
DESCRIPTION: Mathematische Splitting-Strategien.
AUDIT v3.3.2: 100% Konformität zur 'by_heading' Spezifikation.
- Implementiert Hybrid-Safety-Net (Sliding Window für Übergrößen).
- Breadcrumb-Kontext im Window (H1 > H2).
- Sliding Window mit H1-Kontext (Gold-Standard v3.1.0).
DESCRIPTION: Strategien für atomares Sektions-Chunking v3.9.9.
Implementiert das 'Pack-and-Carry-Over' Verfahren nach Regel 1-3.
- Keine redundante Kanten-Injektion.
- Strikte Einhaltung von Sektionsgrenzen via Look-Ahead.
- Fix: Synchronisierung der Parameter mit dem Orchestrator (context_prefix).
"""
from typing import List, Dict, Any, Optional
from .chunking_models import RawBlock, Chunk
from .chunking_utils import estimate_tokens
from .chunking_parser import split_sentences
def _create_context_win(doc_title: str, sec_title: Optional[str], text: str) -> str:
def _create_win(context_prefix: str, sec_title: Optional[str], text: str) -> str:
"""Baut den Breadcrumb-Kontext für das Embedding-Fenster."""
parts = []
if doc_title: parts.append(doc_title)
if sec_title and sec_title != doc_title: parts.append(sec_title)
parts = [context_prefix] if context_prefix else []
# Verhindert Dopplung, falls der Context-Prefix (H1) bereits den Sektionsnamen enthält
if sec_title and f"# {sec_title}" != context_prefix and sec_title not in (context_prefix or ""):
parts.append(sec_title)
prefix = " > ".join(parts)
return f"{prefix}\n{text}".strip() if prefix else text
def strategy_sliding_window(blocks: List[RawBlock],
config: Dict[str, Any],
note_id: str,
context_prefix: str = "") -> List[Chunk]:
def strategy_by_heading(blocks: List[RawBlock], config: Dict[str, Any], note_id: str, context_prefix: str = "") -> List[Chunk]:
"""
Fasst Blöcke zusammen und schneidet bei 'target' Tokens.
Ignoriert H2-Überschriften beim Splitting, um Kontext zu wahren.
"""
target = config.get("target", 400)
max_tokens = config.get("max", 600)
overlap_val = config.get("overlap", (50, 80))
overlap = sum(overlap_val) // 2 if isinstance(overlap_val, tuple) else overlap_val
chunks: List[Chunk] = []
buf: List[RawBlock] = []
def _add(txt, sec, path):
idx = len(chunks)
# H1-Kontext Präfix für das Window-Feld
win = f"{context_prefix}\n{txt}".strip() if context_prefix else txt
chunks.append(Chunk(
id=f"{note_id}#c{idx:02d}", note_id=note_id, index=idx,
text=txt, window=win, token_count=estimate_tokens(txt),
section_title=sec, section_path=path,
neighbors_prev=None, neighbors_next=None
))
def flush():
nonlocal buf
if not buf: return
text_body = "\n\n".join([b.text for b in buf])
sec_title = buf[-1].section_title; sec_path = buf[-1].section_path
if estimate_tokens(text_body) <= max_tokens:
_add(text_body, sec_title, sec_path)
else:
sents = split_sentences(text_body); cur_sents = []; cur_len = 0
for s in sents:
slen = estimate_tokens(s)
if cur_len + slen > target and cur_sents:
_add(" ".join(cur_sents), sec_title, sec_path)
ov_s = []; ov_l = 0
for os in reversed(cur_sents):
if ov_l + estimate_tokens(os) < overlap:
ov_s.insert(0, os); ov_l += estimate_tokens(os)
else: break
cur_sents = list(ov_s); cur_sents.append(s); cur_len = ov_l + slen
else:
cur_sents.append(s); cur_len += slen
if cur_sents:
_add(" ".join(cur_sents), sec_title, sec_path)
buf = []
for b in blocks:
# H2-Überschriften werden ignoriert, um den Zusammenhang zu wahren
if b.kind == "heading": continue
if estimate_tokens("\n\n".join([x.text for x in buf])) + estimate_tokens(b.text) >= target:
flush()
buf.append(b)
flush()
return chunks
def strategy_by_heading(blocks: List[RawBlock], config: Dict[str, Any], note_id: str, doc_title: str = "") -> List[Chunk]:
"""
Splittet Text basierend auf Markdown-Überschriften mit Hybrid-Safety-Net.
Universelle Heading-Strategie mit Carry-Over Logik.
Synchronisiert auf context_prefix für Kompatibilität mit dem Orchestrator.
"""
smart_edge = config.get("enable_smart_edge_allocation", True)
strict = config.get("strict_heading_split", False)
target = config.get("target", 400)
max_tokens = config.get("max", 600)
split_level = config.get("split_level", 2)
overlap = sum(config.get("overlap", (50, 80))) // 2
overlap_cfg = config.get("overlap", (50, 80))
overlap = sum(overlap_cfg) // 2 if isinstance(overlap_cfg, (list, tuple)) else overlap_cfg
chunks: List[Chunk] = []
buf: List[str] = []
cur_tokens = 0
def _add_to_chunks(txt, title, path):
def _emit(txt, title, path):
"""Schreibt den finalen Chunk ohne Text-Modifikationen."""
idx = len(chunks)
win = _create_context_win(doc_title, title, txt)
win = _create_win(context_prefix, title, txt)
chunks.append(Chunk(
id=f"{note_id}#c{idx:02d}", note_id=note_id, index=idx,
text=txt, window=win, token_count=estimate_tokens(txt),
section_title=title, section_path=path,
neighbors_prev=None, neighbors_next=None
section_title=title, section_path=path, neighbors_prev=None, neighbors_next=None
))
def _flush(title, path):
nonlocal buf, cur_tokens
if not buf: return
full_text = "\n\n".join(buf)
if estimate_tokens(full_text) <= max_tokens:
_add_to_chunks(full_text, title, path)
else:
sents = split_sentences(full_text); cur_sents = []; sub_len = 0
for s in sents:
slen = estimate_tokens(s)
if sub_len + slen > target and cur_sents:
_add_to_chunks(" ".join(cur_sents), title, path)
ov_s = []; ov_l = 0
for os in reversed(cur_sents):
if ov_l + estimate_tokens(os) < overlap:
ov_s.insert(0, os); ov_l += estimate_tokens(os)
else: break
cur_sents = list(ov_s); cur_sents.append(s); sub_len = ov_l + slen
else: cur_sents.append(s); sub_len += slen
if cur_sents: _add_to_chunks(" ".join(cur_sents), title, path)
buf = []; cur_tokens = 0
# --- SCHRITT 1: Gruppierung in atomare Sektions-Einheiten ---
sections: List[Dict[str, Any]] = []
curr_blocks = []
for b in blocks:
if b.kind == "heading":
if b.level < split_level: _flush(b.section_title, b.section_path)
elif b.level == split_level:
if strict or cur_tokens >= target: _flush(b.section_title, b.section_path)
if b.kind == "heading" and b.level <= split_level:
if curr_blocks:
sections.append({
"text": "\n\n".join([x.text for x in curr_blocks]),
"meta": curr_blocks[0],
"is_empty": len(curr_blocks) == 1 and curr_blocks[0].kind == "heading"
})
curr_blocks = [b]
else:
curr_blocks.append(b)
if curr_blocks:
sections.append({
"text": "\n\n".join([x.text for x in curr_blocks]),
"meta": curr_blocks[0],
"is_empty": len(curr_blocks) == 1 and curr_blocks[0].kind == "heading"
})
# --- SCHRITT 2: Verarbeitung der Queue ---
queue = list(sections)
current_chunk_text = ""
current_meta = {"title": None, "path": "/"}
# Bestimmung des Modus: Hard-Split wenn smart_edge=False ODER strict=True
is_hard_split_mode = (not smart_edge) or (strict)
while queue:
item = queue.pop(0)
item_text = item["text"]
# Initialisierung für neuen Chunk
if not current_chunk_text:
current_meta["title"] = item["meta"].section_title
current_meta["path"] = item["meta"].section_path
# FALL A: HARD SPLIT MODUS
if is_hard_split_mode:
# Leere Überschriften (z.B. H1 direkt vor H2) verbleiben am nächsten Chunk
if item.get("is_empty", False) and queue:
current_chunk_text = (current_chunk_text + "\n\n" + item_text).strip()
continue
combined = (current_chunk_text + "\n\n" + item_text).strip()
# Wenn durch Verschmelzung das Limit gesprengt würde, vorher flashen
if estimate_tokens(combined) > max_tokens and current_chunk_text:
_emit(current_chunk_text, current_meta["title"], current_meta["path"])
current_chunk_text = item_text
else:
current_chunk_text = combined
# Im Hard-Split wird nach jeder Sektion geflasht
_emit(current_chunk_text, current_meta["title"], current_meta["path"])
current_chunk_text = ""
continue
bt = estimate_tokens(b.text)
if cur_tokens + bt > max_tokens and buf: _flush(b.section_title, b.section_path)
buf.append(b.text); cur_tokens += bt
# FALL B: SMART MODE (Regel 1-3)
combined_text = (current_chunk_text + "\n\n" + item_text).strip() if current_chunk_text else item_text
combined_est = estimate_tokens(combined_text)
if combined_est <= max_tokens:
# Regel 1 & 2: Passt rein laut Schätzung -> Aufnehmen
current_chunk_text = combined_text
else:
if current_chunk_text:
# Regel 2: Flashen an Sektionsgrenze, Item zurücklegen
_emit(current_chunk_text, current_meta["title"], current_meta["path"])
current_chunk_text = ""
queue.insert(0, item)
else:
# Regel 3: Einzelne Sektion zu groß -> Smart Zerlegung
sents = split_sentences(item_text)
header_prefix = item["meta"].text if item["meta"].kind == "heading" else ""
take_sents = []; take_len = 0
while sents:
s = sents.pop(0); slen = estimate_tokens(s)
if take_len + slen > target and take_sents:
sents.insert(0, s); break
take_sents.append(s); take_len += slen
_emit(" ".join(take_sents), current_meta["title"], current_meta["path"])
if sents:
remainder = " ".join(sents)
# Kontext-Erhalt: Überschrift für den Rest wiederholen
if header_prefix and not remainder.startswith(header_prefix):
remainder = header_prefix + "\n\n" + remainder
# Carry-Over: Rest wird vorne in die Queue geschoben
queue.insert(0, {"text": remainder, "meta": item["meta"], "is_split": True})
if current_chunk_text:
_emit(current_chunk_text, current_meta["title"], current_meta["path"])
return chunks
def strategy_sliding_window(blocks: List[RawBlock], config: Dict[str, Any], note_id: str, context_prefix: str = "") -> List[Chunk]:
"""Standard-Sliding-Window für flache Texte ohne Sektionsfokus."""
target = config.get("target", 400); max_tokens = config.get("max", 600)
chunks: List[Chunk] = []; buf: List[RawBlock] = []
for b in blocks:
b_tokens = estimate_tokens(b.text)
curr_tokens = sum(estimate_tokens(x.text) for x in buf) if buf else 0
if curr_tokens + b_tokens > max_tokens and buf:
txt = "\n\n".join([x.text for x in buf]); idx = len(chunks)
win = _create_win(context_prefix, buf[0].section_title, txt)
chunks.append(Chunk(id=f"{note_id}#c{idx:02d}", note_id=note_id, index=idx, text=txt, window=win, token_count=curr_tokens, section_title=buf[0].section_title, section_path=buf[0].section_path, neighbors_prev=None, neighbors_next=None))
buf = []
buf.append(b)
if buf:
last_b = blocks[-1] if blocks else None
_flush(last_b.section_title if last_b else None, last_b.section_path if last_b else "/")
txt = "\n\n".join([x.text for x in buf]); idx = len(chunks)
win = _create_win(context_prefix, buf[0].section_title, txt)
chunks.append(Chunk(id=f"{note_id}#c{idx:02d}", note_id=note_id, index=idx, text=txt, window=win, token_count=estimate_tokens(txt), section_title=buf[0].section_title, section_path=buf[0].section_path, neighbors_prev=None, neighbors_next=None))
return chunks
+4 -2
View File
@@ -3,7 +3,7 @@ FILE: app/core/database/qdrant.py
DESCRIPTION: Qdrant-Client Factory und Schema-Management.
Erstellt Collections und Payload-Indizes.
MODULARISIERUNG: Verschoben in das database-Paket für WP-14.
VERSION: 2.2.1
VERSION: 2.2.2 (WP-Fix: Index für target_section)
STATUS: Active
DEPENDENCIES: qdrant_client, dataclasses, os
"""
@@ -124,7 +124,7 @@ def ensure_payload_indexes(client: QdrantClient, prefix: str) -> None:
Stellt sicher, dass alle benötigten Payload-Indizes für die Suche existieren.
- notes: note_id, type, title, updated, tags
- chunks: note_id, chunk_id, index, type, tags
- edges: note_id, kind, scope, source_id, target_id, chunk_id
- edges: note_id, kind, scope, source_id, target_id, chunk_id, target_section
"""
notes, chunks, edges = collection_names(prefix)
@@ -156,6 +156,8 @@ def ensure_payload_indexes(client: QdrantClient, prefix: str) -> None:
("source_id", rest.PayloadSchemaType.KEYWORD),
("target_id", rest.PayloadSchemaType.KEYWORD),
("chunk_id", rest.PayloadSchemaType.KEYWORD),
# NEU: Index für Section-Links (WP-15b)
("target_section", rest.PayloadSchemaType.KEYWORD),
]:
_ensure_index(client, edges, field, schema)
+11 -2
View File
@@ -1,10 +1,10 @@
"""
FILE: app/core/database/qdrant_points.py
DESCRIPTION: Object-Mapper für Qdrant. Konvertiert JSON-Payloads (Notes, Chunks, Edges) in PointStructs und generiert deterministische UUIDs.
VERSION: 1.5.0
VERSION: 1.5.1 (WP-Fix: Explicit Target Section Support)
STATUS: Active
DEPENDENCIES: qdrant_client, uuid, os
LAST_ANALYSIS: 2025-12-15
LAST_ANALYSIS: 2025-12-29
"""
from __future__ import annotations
import os
@@ -46,16 +46,25 @@ def points_for_chunks(prefix: str, chunk_payloads: List[dict], vectors: List[Lis
return chunks_col, points
def _normalize_edge_payload(pl: dict) -> dict:
"""Normalisiert Edge-Felder und sichert Schema-Konformität."""
kind = pl.get("kind") or pl.get("edge_type") or "edge"
source_id = pl.get("source_id") or pl.get("src_id") or "unknown-src"
target_id = pl.get("target_id") or pl.get("dst_id") or "unknown-tgt"
seq = pl.get("seq") or pl.get("order") or pl.get("index")
# WP-Fix: target_section explizit durchreichen
target_section = pl.get("target_section")
pl.setdefault("kind", kind)
pl.setdefault("source_id", source_id)
pl.setdefault("target_id", target_id)
if seq is not None and "seq" not in pl:
pl["seq"] = seq
if target_section is not None:
pl["target_section"] = target_section
return pl
def points_for_edges(prefix: str, edge_payloads: List[dict]) -> Tuple[str, List[rest.PointStruct]]:
-10
View File
@@ -1,10 +0,0 @@
"""
FILE: app/core/derive_edges.py
DESCRIPTION: Facade für das neue graph Package.
WP-14: Modularisierung abgeschlossen.
VERSION: 2.2.0
"""
from .graph.graph_derive_edges import build_edges_for_note
from .graph.graph_utils import PROVENANCE_PRIORITY
__all__ = ["build_edges_for_note", "PROVENANCE_PRIORITY"]
+11 -3
View File
@@ -1,13 +1,15 @@
"""
FILE: app/core/graph/graph_db_adapter.py
DESCRIPTION: Datenbeschaffung aus Qdrant für den Graphen.
AUDIT v1.1.0: Nutzt nun die zentrale database-Infrastruktur für Namen.
AUDIT v1.1.1: Volle Unterstützung für WP-15c Metadaten.
Stellt sicher, dass 'target_section' und 'provenance' für die
Super-Edge-Aggregation im Retriever geladen werden.
"""
from typing import List, Dict, Optional
from qdrant_client import QdrantClient
from qdrant_client.http import models as rest
# ENTSCHEIDENDER FIX: Nutzt die neue Infrastruktur für konsistente Collection-Namen
# Nutzt die zentrale Infrastruktur für konsistente Collection-Namen (WP-14)
from app.core.database import collection_names
def fetch_edges_from_qdrant(
@@ -19,14 +21,16 @@ def fetch_edges_from_qdrant(
) -> List[Dict]:
"""
Holt Edges aus der Datenbank basierend auf Seed-IDs.
Filtert auf source_id, target_id oder note_id.
WP-15c: Erhält alle Metadaten für das Note-Level Diversity Pooling.
"""
if not seeds or limit <= 0:
return []
# Konsistente Namensauflösung via database-Paket
# Rückgabe: (notes_col, chunks_col, edges_col)
_, _, edges_col = collection_names(prefix)
# Wir suchen Kanten, bei denen die Seed-IDs entweder Quelle, Ziel oder Kontext-Note sind.
seed_conditions = []
for field in ("source_id", "target_id", "note_id"):
for s in seeds:
@@ -35,6 +39,7 @@ def fetch_edges_from_qdrant(
)
seeds_filter = rest.Filter(should=seed_conditions) if seed_conditions else None
# Optionaler Filter auf spezifische Kanten-Typen (z.B. für Intent-Routing)
type_filter = None
if edge_types:
type_conds = [
@@ -52,6 +57,7 @@ def fetch_edges_from_qdrant(
flt = rest.Filter(must=must) if must else None
# Abfrage via Qdrant Scroll API
# WICHTIG: with_payload=True lädt alle Metadaten (target_section, provenance etc.)
pts, _ = client.scroll(
collection_name=edges_col,
scroll_filter=flt,
@@ -60,4 +66,6 @@ def fetch_edges_from_qdrant(
with_vectors=False,
)
# Wir geben das vollständige Payload zurück, damit der Retriever
# alle Signale für die Super-Edge-Aggregation und das Scoring hat.
return [dict(p.payload) for p in pts if p.payload]
+93 -36
View File
@@ -1,10 +1,14 @@
"""
FILE: app/core/graph/graph_derive_edges.py
DESCRIPTION: Hauptlogik zur Kanten-Aggregation und De-Duplizierung.
WP-15b/c Audit:
- Präzises Sektions-Splitting via parse_link_target.
- Eindeutige ID-Generierung pro Sektions-Variante (Multigraph).
- Ermöglicht dem Retriever die Super-Edge-Aggregation.
"""
from typing import List, Optional, Dict, Tuple
from .graph_utils import (
_get, _edge, _mk_edge_id, _dedupe_seq,
_get, _edge, _mk_edge_id, _dedupe_seq, parse_link_target,
PROVENANCE_PRIORITY, load_types_registry, get_edge_defaults_for
)
from .graph_extractors import (
@@ -17,31 +21,45 @@ def build_edges_for_note(
note_level_references: Optional[List[str]] = None,
include_note_scope_refs: bool = False,
) -> List[dict]:
"""Erzeugt und aggregiert alle Kanten für eine Note (WP-15b)."""
"""
Erzeugt und aggregiert alle Kanten für eine Note.
Sorgt für die physische Trennung von Sektions-Links via Edge-ID.
"""
edges: List[dict] = []
# note_type für die Ermittlung der edge_defaults (types.yaml)
note_type = _get(chunks[0], "type") if chunks else "concept"
# 1) Struktur-Kanten (belongs_to, next/prev)
# 1) Struktur-Kanten (Internal: belongs_to, next/prev)
# Diese erhalten die Provenienz 'structure' und sind in der Registry geschützt.
for idx, ch in enumerate(chunks):
cid = _get(ch, "chunk_id", "id")
if not cid: continue
# Verbindung Chunk -> Note
edges.append(_edge("belongs_to", "chunk", cid, note_id, note_id, {
"chunk_id": cid, "edge_id": _mk_edge_id("belongs_to", cid, note_id, "chunk", "structure:belongs_to"),
"provenance": "structure", "rule_id": "structure:belongs_to", "confidence": PROVENANCE_PRIORITY["structure:belongs_to"]
"chunk_id": cid,
"edge_id": _mk_edge_id("belongs_to", cid, note_id, "chunk", "structure:belongs_to"),
"provenance": "structure",
"rule_id": "structure:belongs_to",
"confidence": PROVENANCE_PRIORITY["structure:belongs_to"]
}))
# Horizontale Verkettung (Ordnung)
if idx < len(chunks) - 1:
next_id = _get(chunks[idx+1], "chunk_id", "id")
if next_id:
edges.append(_edge("next", "chunk", cid, next_id, note_id, {
"chunk_id": cid, "edge_id": _mk_edge_id("next", cid, next_id, "chunk", "structure:order"),
"chunk_id": cid,
"edge_id": _mk_edge_id("next", cid, next_id, "chunk", "structure:order"),
"provenance": "structure", "rule_id": "structure:order", "confidence": PROVENANCE_PRIORITY["structure:order"]
}))
edges.append(_edge("prev", "chunk", next_id, cid, note_id, {
"chunk_id": next_id, "edge_id": _mk_edge_id("prev", next_id, cid, "chunk", "structure:order"),
"chunk_id": next_id,
"edge_id": _mk_edge_id("prev", next_id, cid, "chunk", "structure:order"),
"provenance": "structure", "rule_id": "structure:order", "confidence": PROVENANCE_PRIORITY["structure:order"]
}))
# 2) Inhaltliche Kanten
# 2) Inhaltliche Kanten (Explicit & Candidate Pool)
reg = load_types_registry()
defaults = get_edge_defaults_for(note_type, reg)
refs_all: List[str] = []
@@ -51,62 +69,101 @@ def build_edges_for_note(
if not cid: continue
raw = _get(ch, "window") or _get(ch, "text") or ""
# Typed & Candidate Pool (WP-15b Integration)
# A. Typed Relations (Inline [[rel:kind|target]])
typed, rem = extract_typed_relations(raw)
for k, t in typed:
edges.append(_edge(k, "chunk", cid, t, note_id, {
"chunk_id": cid, "edge_id": _mk_edge_id(k, cid, t, "chunk", "inline:rel"),
for k, raw_t in typed:
t, sec = parse_link_target(raw_t, note_id)
if not t: continue
payload = {
"chunk_id": cid,
# WP-Fix: Variant=sec sorgt für eindeutige ID pro Sektion
"edge_id": _mk_edge_id(k, cid, t, "chunk", "inline:rel", variant=sec),
"provenance": "explicit", "rule_id": "inline:rel", "confidence": PROVENANCE_PRIORITY["inline:rel"]
}))
}
if sec: payload["target_section"] = sec
edges.append(_edge(k, "chunk", cid, t, note_id, payload))
# B. Candidate Pool (WP-15b Validierte KI-Kanten)
pool = ch.get("candidate_pool") or ch.get("candidate_edges") or []
for cand in pool:
t, k, p = cand.get("to"), cand.get("kind", "related_to"), cand.get("provenance", "semantic_ai")
raw_t, k, p = cand.get("to"), cand.get("kind", "related_to"), cand.get("provenance", "semantic_ai")
t, sec = parse_link_target(raw_t, note_id)
if t:
edges.append(_edge(k, "chunk", cid, t, note_id, {
"chunk_id": cid, "edge_id": _mk_edge_id(k, cid, t, "chunk", f"candidate:{p}"),
payload = {
"chunk_id": cid,
"edge_id": _mk_edge_id(k, cid, t, "chunk", f"candidate:{p}", variant=sec),
"provenance": p, "rule_id": f"candidate:{p}", "confidence": PROVENANCE_PRIORITY.get(p, 0.90)
}))
}
if sec: payload["target_section"] = sec
edges.append(_edge(k, "chunk", cid, t, note_id, payload))
# Callouts & Wikilinks
# C. Callouts (> [!edge])
call_pairs, rem2 = extract_callout_relations(rem)
for k, t in call_pairs:
edges.append(_edge(k, "chunk", cid, t, note_id, {
"chunk_id": cid, "edge_id": _mk_edge_id(k, cid, t, "chunk", "callout:edge"),
for k, raw_t in call_pairs:
t, sec = parse_link_target(raw_t, note_id)
if not t: continue
payload = {
"chunk_id": cid,
"edge_id": _mk_edge_id(k, cid, t, "chunk", "callout:edge", variant=sec),
"provenance": "explicit", "rule_id": "callout:edge", "confidence": PROVENANCE_PRIORITY["callout:edge"]
}))
}
if sec: payload["target_section"] = sec
edges.append(_edge(k, "chunk", cid, t, note_id, payload))
# D. Standard Wikilinks & Typ-Defaults
refs = extract_wikilinks(rem2)
for r in refs:
edges.append(_edge("references", "chunk", cid, r, note_id, {
"chunk_id": cid, "ref_text": r, "edge_id": _mk_edge_id("references", cid, r, "chunk", "explicit:wikilink"),
for raw_r in refs:
r, sec = parse_link_target(raw_r, note_id)
if not r: continue
payload = {
"chunk_id": cid, "ref_text": raw_r,
"edge_id": _mk_edge_id("references", cid, r, "chunk", "explicit:wikilink", variant=sec),
"provenance": "explicit", "rule_id": "explicit:wikilink", "confidence": PROVENANCE_PRIORITY["explicit:wikilink"]
}))
}
if sec: payload["target_section"] = sec
edges.append(_edge("references", "chunk", cid, r, note_id, payload))
# Automatische Kanten-Vererbung aus types.yaml
for rel in defaults:
if rel != "references":
edges.append(_edge(rel, "chunk", cid, r, note_id, {
"chunk_id": cid, "edge_id": _mk_edge_id(rel, cid, r, "chunk", f"edge_defaults:{rel}"),
def_payload = {
"chunk_id": cid,
"edge_id": _mk_edge_id(rel, cid, r, "chunk", f"edge_defaults:{rel}", variant=sec),
"provenance": "rule", "rule_id": f"edge_defaults:{rel}", "confidence": PROVENANCE_PRIORITY["edge_defaults"]
}))
refs_all.extend(refs)
}
if sec: def_payload["target_section"] = sec
edges.append(_edge(rel, "chunk", cid, r, note_id, def_payload))
refs_all.extend([parse_link_target(r, note_id)[0] for r in refs])
# 3) Note-Scope & De-Duplizierung
# 3) Note-Scope (Grobe Struktur-Verbindungen)
if include_note_scope_refs:
refs_note = _dedupe_seq((refs_all or []) + (note_level_references or []))
cleaned_note_refs = [parse_link_target(r, note_id)[0] for r in (note_level_references or [])]
refs_note = _dedupe_seq((refs_all or []) + cleaned_note_refs)
for r in refs_note:
if not r: continue
edges.append(_edge("references", "note", note_id, r, note_id, {
"edge_id": _mk_edge_id("references", note_id, r, "note", "explicit:note_scope"),
"provenance": "explicit", "confidence": PROVENANCE_PRIORITY["explicit:note_scope"]
}))
# Backlinks zur Stärkung der Bidirektionalität
edges.append(_edge("backlink", "note", r, note_id, note_id, {
"edge_id": _mk_edge_id("backlink", r, note_id, "note", "derived:backlink"),
"provenance": "rule", "confidence": PROVENANCE_PRIORITY["derived:backlink"]
}))
unique_map: Dict[Tuple[str, str, str], dict] = {}
# 4) De-Duplizierung (In-Place)
# Da die EDGE-ID nun die Sektion (variant) enthält, bleiben Links auf
# unterschiedliche Abschnitte derselben Note erhalten.
unique_map: Dict[str, dict] = {}
for e in edges:
key = (str(e.get("source_id")), str(e.get("target_id")), str(e.get("kind")))
if key not in unique_map or e.get("confidence", 0) > unique_map[key].get("confidence", 0):
unique_map[key] = e
eid = e["edge_id"]
# Höhere Confidence gewinnt bei identischer ID
if eid not in unique_map or e.get("confidence", 0) > unique_map[eid].get("confidence", 0):
unique_map[eid] = e
return list(unique_map.values())
+93 -21
View File
@@ -1,25 +1,36 @@
"""
FILE: app/core/graph/graph_extractors.py
DESCRIPTION: Regex-basierte Extraktion von Relationen aus Text.
AUDIT:
- Regex für Wikilinks liberalisiert (Umlaute, Sonderzeichen).
- Callout-Parser erweitert für Multi-Line-Listen und Header-Typen.
"""
import re
from typing import List, Tuple
_WIKILINK_RE = re.compile(r"\[\[(?:[^\|\]]+\|)?([a-zA-Z0-9_\-#:. ]+)\]\]")
# Erlaube alle Zeichen außer ']' im Target (fängt Umlaute, Emojis, '&', '#' ab)
_WIKILINK_RE = re.compile(r"\[\[(?:[^\|\]]+\|)?([^\]]+)\]\]")
_REL_PIPE = re.compile(r"\[\[\s*rel:(?P<kind>[a-z_]+)\s*\|\s*(?P<target>[^\]]+?)\s*\]\]", re.IGNORECASE)
_REL_SPACE = re.compile(r"\[\[\s*rel:(?P<kind>[a-z_]+)\s+(?P<target>[^\]]+?)\s*\]\]", re.IGNORECASE)
_REL_TEXT = re.compile(r"rel\s*:\s*(?P<kind>[a-z_]+)\s*\[\[\s*(?P<target>[^\]]+?)\s*\]\]", re.IGNORECASE)
_CALLOUT_START = re.compile(r"^\s*>\s*\[!edge\]\s*(.*)$", re.IGNORECASE)
# Erkennt "kind: targets..."
_REL_LINE = re.compile(r"^(?P<kind>[a-z_]+)\s*:\s*(?P<targets>.+?)\s*$", re.IGNORECASE)
_WIKILINKS_IN_LINE = re.compile(r"\[\[([^\]]+)\]\]")
# Erkennt reine Typen (z.B. "depends_on" im Header)
_SIMPLE_KIND = re.compile(r"^[a-z_]+$", re.IGNORECASE)
def extract_typed_relations(text: str) -> Tuple[List[Tuple[str,str]], str]:
"""Extrahiert [[rel:KIND|Target]]."""
def extract_typed_relations(text: str) -> Tuple[List[Tuple[str, str]], str]:
"""
Findet Inline-Relationen wie [[rel:depends_on Target]].
Gibt (Liste[(kind, target)], bereinigter_text) zurück.
"""
if not text: return [], ""
pairs = []
def _collect(m):
k, t = (m.group("kind") or "").strip().lower(), (m.group("target") or "").strip()
if k and t: pairs.append((k, t))
k, t = m.group("kind").strip().lower(), m.group("target").strip()
pairs.append((k, t))
return ""
text = _REL_PIPE.sub(_collect, text)
text = _REL_SPACE.sub(_collect, text)
@@ -27,29 +38,90 @@ def extract_typed_relations(text: str) -> Tuple[List[Tuple[str,str]], str]:
return pairs, text
def extract_callout_relations(text: str) -> Tuple[List[Tuple[str,str]], str]:
"""Verarbeitet Obsidian [!edge]-Callouts."""
"""
Verarbeitet Obsidian [!edge]-Callouts.
Unterstützt zwei Formate:
1. Explizit: "kind: [[Target]]"
2. Implizit (Header): "> [!edge] kind" gefolgt von "[[Target]]" Zeilen
"""
if not text: return [], text
lines = text.splitlines(); out_pairs, keep_lines, i = [], [], 0
lines = text.splitlines()
out_pairs = []
keep_lines = []
i = 0
while i < len(lines):
m = _CALLOUT_START.match(lines[i])
line = lines[i]
m = _CALLOUT_START.match(line)
if not m:
keep_lines.append(lines[i]); i += 1; continue
block_lines = [m.group(1)] if m.group(1).strip() else []
keep_lines.append(line)
i += 1
continue
# Callout-Block gefunden. Wir sammeln alle relevanten Zeilen.
block_lines = []
# Header Content prüfen (z.B. "type" aus "> [!edge] type")
header_raw = m.group(1).strip()
if header_raw:
block_lines.append(header_raw)
i += 1
while i < len(lines) and lines[i].lstrip().startswith('>'):
block_lines.append(lines[i].lstrip()[1:].lstrip()); i += 1
# Entferne '>' und führende Leerzeichen
content = lines[i].lstrip()[1:].lstrip()
if content:
block_lines.append(content)
i += 1
# Verarbeitung des Blocks
current_kind = None
# Heuristik: Ist die allererste Zeile (meist aus dem Header) ein reiner Typ?
# Dann setzen wir diesen als Default für den Block.
if block_lines:
first = block_lines[0]
# Wenn es NICHT wie "Key: Value" aussieht, aber wie ein Wort:
if not _REL_LINE.match(first) and _SIMPLE_KIND.match(first):
current_kind = first.lower()
for bl in block_lines:
# 1. Prüfen auf explizites "Kind: Targets" (überschreibt Header-Typ für diese Zeile)
mrel = _REL_LINE.match(bl)
if not mrel: continue
kind, targets = mrel.group("kind").strip().lower(), mrel.group("targets") or ""
found = _WIKILINKS_IN_LINE.findall(targets)
if mrel:
line_kind = mrel.group("kind").strip().lower()
targets = mrel.group("targets")
# Links extrahieren
found = _WIKILINK_RE.findall(targets)
if found:
for t in found: out_pairs.append((line_kind, t.strip()))
else:
# Fallback für kommagetrennten Plaintext
for raw in re.split(r"[,;]", targets):
if raw.strip(): out_pairs.append((line_kind, raw.strip()))
# Wenn wir eine explizite Zeile gefunden haben, aktualisieren wir NICHT
# den current_kind für nachfolgende Zeilen (Design-Entscheidung: lokal scope),
# oder wir machen es doch?
# Üblicher ist: Header setzt Default, Zeile überschreibt lokal.
# Wir lassen current_kind also unangetastet.
continue
# 2. Kein Key:Value Muster -> Prüfen auf Links, die den current_kind nutzen
found = _WIKILINK_RE.findall(bl)
if found:
for t in found: out_pairs.append((kind, t.strip()))
else:
for raw in re.split(r"[,;]", targets):
if raw.strip(): out_pairs.append((kind, raw.strip()))
if current_kind:
for t in found: out_pairs.append((current_kind, t.strip()))
else:
# Link ohne Typ und ohne Header-Typ.
# Wird ignoriert oder könnte als 'related_to' fallback dienen.
# Aktuell: Ignorieren, um False Positives zu vermeiden.
pass
return out_pairs, "\n".join(keep_lines)
def extract_wikilinks(text: str) -> List[str]:
"""Extrahiert Standard-Wikilinks."""
return [m.group(1).strip() for m in _WIKILINK_RE.finditer(text or "")]
"""Findet Standard-Wikilinks [[Target]] oder [[Alias|Target]]."""
if not text: return []
return [m.strip() for m in _WIKILINK_RE.findall(text) if m.strip()]
+40 -13
View File
@@ -2,8 +2,9 @@
FILE: app/core/graph/graph_subgraph.py
DESCRIPTION: In-Memory Repräsentation eines Graphen für Scoring und Analyse.
Zentrale Komponente für die Graph-Expansion (BFS) und Bonus-Berechnung.
MODULARISIERUNG: Teil des graph-Pakets (WP-14).
VERSION: 1.1.0
WP-15c Update: Erhalt von Metadaten (target_section, provenance)
für präzises Retrieval-Reasoning.
VERSION: 1.2.0
STATUS: Active
"""
import math
@@ -22,6 +23,7 @@ class Subgraph:
"""
def __init__(self) -> None:
# adj speichert nun vollständige Payloads statt nur Tripel
self.adj: DefaultDict[str, List[Dict]] = defaultdict(list)
self.reverse_adj: DefaultDict[str, List[Dict]] = defaultdict(list)
self.in_degree: DefaultDict[str, int] = defaultdict(int)
@@ -30,31 +32,49 @@ class Subgraph:
def add_edge(self, e: Dict) -> None:
"""
Fügt eine Kante hinzu und aktualisiert Indizes.
Unterstützt Kontext-Notes für verbesserte Graph-Konnektivität.
WP-15c: Speichert das vollständige Payload für den Explanation Layer.
"""
src = e.get("source")
tgt = e.get("target")
kind = e.get("kind")
weight = e.get("weight", EDGE_BASE_WEIGHTS.get(kind, 0.0))
# Das gesamte Payload wird als Kanten-Objekt behalten
# Wir stellen sicher, dass alle relevanten Metadaten vorhanden sind
edge_data = {
"source": src,
"target": tgt,
"kind": kind,
"weight": e.get("weight", EDGE_BASE_WEIGHTS.get(kind, 0.0)),
"provenance": e.get("provenance", "rule"),
"confidence": e.get("confidence", 1.0),
"target_section": e.get("target_section"), # Essentiell für Präzision
"is_super_edge": e.get("is_super_edge", False)
}
owner = e.get("note_id")
if not src or not tgt:
return
# 1. Forward-Kante
self.adj[src].append({"target": tgt, "kind": kind, "weight": weight})
self.adj[src].append(edge_data)
self.out_degree[src] += 1
self.in_degree[tgt] += 1
# 2. Reverse-Kante (für WP-04b Explanation Layer)
self.reverse_adj[tgt].append({"source": src, "kind": kind, "weight": weight})
# 2. Reverse-Kante (für Explanation Layer & Backlinks)
self.reverse_adj[tgt].append(edge_data)
# 3. Kontext-Note Handling (erhöht die Zentralität der Parent-Note)
if owner and owner != src:
self.adj[owner].append({"target": tgt, "kind": kind, "weight": weight})
# Wir erstellen eine virtuelle Kontext-Kante
ctx_edge = edge_data.copy()
ctx_edge["source"] = owner
ctx_edge["via_context"] = True
self.adj[owner].append(ctx_edge)
self.out_degree[owner] += 1
if owner != tgt:
self.reverse_adj[tgt].append({"source": owner, "kind": kind, "weight": weight, "via_context": True})
self.reverse_adj[tgt].append(ctx_edge)
self.in_degree[owner] += 1
def aggregate_edge_bonus(self, node_id: str) -> float:
@@ -73,14 +93,15 @@ class Subgraph:
indeg = self.in_degree.get(node_id, 0)
if indeg <= 0:
return 0.0
# math.log1p(x) entspricht log(1+x)
return min(math.log1p(indeg) / 10.0, 0.15)
def get_outgoing_edges(self, node_id: str) -> List[Dict[str, Any]]:
"""Gibt alle ausgehenden Kanten einer Node zurück."""
"""Gibt alle ausgehenden Kanten einer Node inkl. Metadaten zurück."""
return self.adj.get(node_id, [])
def get_incoming_edges(self, node_id: str) -> List[Dict[str, Any]]:
"""Gibt alle eingehenden Kanten einer Node zurück."""
"""Gibt alle eingehenden Kanten einer Node inkl. Metadaten zurück."""
return self.reverse_adj.get(node_id, [])
@@ -111,13 +132,19 @@ def expand(
src, tgt = pl.get("source_id"), pl.get("target_id")
if not src or not tgt: continue
sg.add_edge({
# WP-15c: Wir übergeben das vollständige Payload an add_edge
edge_payload = {
"source": src,
"target": tgt,
"kind": pl.get("kind", "edge"),
"weight": calculate_edge_weight(pl),
"note_id": pl.get("note_id"),
})
"provenance": pl.get("provenance", "rule"),
"confidence": pl.get("confidence", 1.0),
"target_section": pl.get("target_section")
}
sg.add_edge(edge_payload)
# BFS Logik: Neue Ziele in die nächste Frontier aufnehmen
if tgt not in visited:
+35 -4
View File
@@ -1,10 +1,11 @@
"""
FILE: app/core/graph/graph_utils.py
DESCRIPTION: Basale Werkzeuge, ID-Generierung und Provenance-Konfiguration für den Graphen.
AUDIT: Erweitert um parse_link_target für sauberes Section-Splitting (WP-Fix).
"""
import os
import hashlib
from typing import Iterable, List, Optional, Set, Any
from typing import Iterable, List, Optional, Set, Any, Tuple
try:
import yaml
@@ -40,10 +41,19 @@ def _dedupe_seq(seq: Iterable[str]) -> List[str]:
seen.add(s); out.append(s)
return out
def _mk_edge_id(kind: str, s: str, t: str, scope: str, rule_id: Optional[str] = None) -> str:
"""Erzeugt eine deterministische 12-Byte ID mittels BLAKE2s."""
def _mk_edge_id(kind: str, s: str, t: str, scope: str, rule_id: Optional[str] = None, variant: Optional[str] = None) -> str:
"""
Erzeugt eine deterministische 12-Byte ID mittels BLAKE2s.
WP-Fix: 'variant' (z.B. Section) fließt in den Hash ein, um mehrere Kanten
zum gleichen Target-Node (aber unterschiedlichen Abschnitten) zu unterscheiden.
"""
base = f"{kind}:{s}->{t}#{scope}"
if rule_id: base += f"|{rule_id}"
if rule_id:
base += f"|{rule_id}"
if variant:
base += f"|{variant}" # <--- Hier entsteht die Eindeutigkeit für verschiedene Sections
return hashlib.blake2s(base.encode("utf-8"), digest_size=12).hexdigest()
def _edge(kind: str, scope: str, source_id: str, target_id: str, note_id: str, extra: Optional[dict] = None) -> dict:
@@ -59,6 +69,27 @@ def _edge(kind: str, scope: str, source_id: str, target_id: str, note_id: str, e
if extra: pl.update(extra)
return pl
def parse_link_target(raw: str, current_note_id: Optional[str] = None) -> Tuple[str, Optional[str]]:
"""
Zerlegt einen Link (z.B. 'Note#Section') in Target-ID und Section.
Behandelt Self-Links ('#Section'), indem current_note_id eingesetzt wird.
Returns:
(target_id, target_section)
"""
if not raw:
return "", None
parts = raw.split("#", 1)
target = parts[0].strip()
section = parts[1].strip() if len(parts) > 1 else None
# Handle Self-Link [[#Section]] -> target wird zu current_note_id
if not target and section and current_note_id:
target = current_note_id
return target, section
def load_types_registry() -> dict:
"""Lädt die YAML-Registry."""
p = os.getenv("MINDNET_TYPES_FILE", "./config/types.yaml")
-10
View File
@@ -1,10 +0,0 @@
"""
FILE: app/core/graph_adapter.py
DESCRIPTION: Facade für das neue graph Package (Adapter-Teil).
WP-14: Modularisierung abgeschlossen.
VERSION: 0.5.0
"""
from .graph.graph_subgraph import Subgraph, expand
from .graph.graph_weights import EDGE_BASE_WEIGHTS
__all__ = ["Subgraph", "expand", "EDGE_BASE_WEIGHTS"]
+25 -16
View File
@@ -3,9 +3,8 @@ FILE: app/core/ingestion/ingestion_note_payload.py
DESCRIPTION: Baut das JSON-Objekt für mindnet_notes.
FEATURES:
- Multi-Hash (body/full) für flexible Change Detection.
- Fix v2.4.4: Integration der zentralen Registry (WP-14) für konsistente Defaults.
VERSION: 2.4.4
STATUS: Active
- Fix v2.4.5: Präzise Hash-Logik für Profil-Änderungen.
- Integration der zentralen Registry (WP-14).
"""
from __future__ import annotations
from typing import Any, Dict, Tuple, Optional
@@ -45,14 +44,23 @@ def _compute_hash(content: str) -> str:
return hashlib.sha256(content.encode("utf-8")).hexdigest()
def _get_hash_source_content(n: Dict[str, Any], mode: str) -> str:
"""Generiert den Hash-Input-String basierend auf Body oder Metadaten."""
body = str(n.get("body") or "")
"""
Generiert den Hash-Input-String basierend auf Body oder Metadaten.
Fix: Inkludiert nun alle entscheidungsrelevanten Profil-Parameter.
"""
body = str(n.get("body") or "").strip()
if mode == "body": return body
if mode == "full":
fm = n.get("frontmatter") or {}
meta_parts = []
# Sortierte Liste für deterministische Hashes
for k in sorted(["title", "type", "status", "tags", "chunking_profile", "chunk_profile", "retriever_weight"]):
# Wir inkludieren alle Felder, die das Chunking oder Retrieval beeinflussen
# Jede Änderung hier führt nun zwingend zu einem neuen Full-Hash
keys = [
"title", "type", "status", "tags",
"chunking_profile", "chunk_profile",
"retriever_weight", "split_level", "strict_heading_split"
]
for k in sorted(keys):
val = fm.get(k)
if val is not None: meta_parts.append(f"{k}:{val}")
return f"{'|'.join(meta_parts)}||{body}"
@@ -79,11 +87,11 @@ def _cfg_defaults(reg: dict) -> dict:
def make_note_payload(note: Any, *args, **kwargs) -> Dict[str, Any]:
"""
Baut das Note-Payload inklusive Multi-Hash und Audit-Validierung.
WP-14: Nutzt nun die zentrale Registry für alle Fallbacks.
WP-14: Nutzt die zentrale Registry für alle Fallbacks.
"""
n = _as_dict(note)
# Nutzt übergebene Registry oder lädt sie global
# Registry & Context Settings
reg = kwargs.get("types_cfg") or load_type_registry()
hash_source = kwargs.get("hash_source", "parsed")
hash_normalize = kwargs.get("hash_normalize", "canonical")
@@ -96,7 +104,6 @@ def make_note_payload(note: Any, *args, **kwargs) -> Dict[str, Any]:
ingest_cfg = reg.get("ingestion_settings", {})
# --- retriever_weight Audit ---
# Priorität: Frontmatter -> Typ-Config -> globale Config -> Env-Var
default_rw = float(os.environ.get("MINDNET_DEFAULT_RETRIEVER_WEIGHT", 1.0))
retriever_weight = fm.get("retriever_weight")
if retriever_weight is None:
@@ -107,14 +114,13 @@ def make_note_payload(note: Any, *args, **kwargs) -> Dict[str, Any]:
retriever_weight = default_rw
# --- chunk_profile Audit ---
# Nutzt nun primär die ingestion_settings aus der Registry
chunk_profile = fm.get("chunking_profile") or fm.get("chunk_profile")
if chunk_profile is None:
chunk_profile = cfg_type.get("chunking_profile") or cfg_type.get("chunk_profile")
if chunk_profile is None:
chunk_profile = ingest_cfg.get("default_chunk_profile", cfg_def.get("chunking_profile", "sliding_standard"))
# --- edge_defaults ---
# --- edge_defaults Audit ---
edge_defaults = fm.get("edge_defaults")
if edge_defaults is None:
edge_defaults = cfg_type.get("edge_defaults", cfg_def.get("edge_defaults", []))
@@ -138,21 +144,24 @@ def make_note_payload(note: Any, *args, **kwargs) -> Dict[str, Any]:
}
# --- MULTI-HASH ---
# Generiert Hashes für Change Detection
# Generiert Hashes für Change Detection (WP-15b)
for mode in ["body", "full"]:
content = _get_hash_source_content(n, mode)
payload["hashes"][f"{mode}:{hash_source}:{hash_normalize}"] = _compute_hash(content)
# Metadaten Anreicherung
# Metadaten Anreicherung (Tags, Aliases, Zeitstempel)
tags = fm.get("tags") or fm.get("keywords") or n.get("tags")
if tags: payload["tags"] = _ensure_list(tags)
if fm.get("aliases"): payload["aliases"] = _ensure_list(fm.get("aliases"))
aliases = fm.get("aliases")
if aliases: payload["aliases"] = _ensure_list(aliases)
for k in ("created", "modified", "date"):
v = fm.get(k) or n.get(k)
if v: payload[k] = str(v)
if n.get("body"): payload["fulltext"] = str(n["body"])
if n.get("body"):
payload["fulltext"] = str(n["body"])
# Final JSON Validation Audit
json.loads(json.dumps(payload, ensure_ascii=False))
+36 -11
View File
@@ -1,11 +1,11 @@
"""
FILE: app/core/ingestion/ingestion_processor.py
DESCRIPTION: Der zentrale IngestionService (Orchestrator).
WP-14: Modularisierung der Datenbank-Ebene (app.core.database).
WP-25a: Integration der Mixture of Experts (MoE) Architektur.
WP-15b: Two-Pass Workflow mit globalem Kontext-Cache.
WP-20/22: Cloud-Resilienz und Content-Lifecycle integriert.
AUDIT v2.13.10: Umstellung auf app.core.database Infrastruktur.
VERSION: 2.13.10
AUDIT v2.14.0: Synchronisierung der Profil-Auflösung mit MoE-Experten.
VERSION: 2.14.0 (WP-25a: MoE & Profile Support)
STATUS: Active
"""
import logging
@@ -38,7 +38,7 @@ from .ingestion_chunk_payload import make_chunk_payloads
# Fallback für Edges (Struktur-Verknüpfung)
try:
from app.core.derive_edges import build_edges_for_note
from app.core.graph.graph_derive_edges import build_edges_for_note
except ImportError:
def build_edges_for_note(*args, **kwargs): return []
@@ -55,11 +55,16 @@ class IngestionService:
# Synchronisierung der Konfiguration mit dem Instanz-Präfix
self.cfg.prefix = self.prefix
self.client = get_client(self.cfg)
self.dim = self.settings.VECTOR_SIZE
self.registry = load_type_registry()
self.embedder = EmbeddingsClient()
self.llm = LLMService()
# WP-25a: Auflösung der Dimension über das Embedding-Profil (MoE)
embed_cfg = self.llm.profiles.get("embedding_expert", {})
self.dim = embed_cfg.get("dimensions") or self.settings.VECTOR_SIZE
# Festlegen, welcher Hash für die Change-Detection maßgeblich ist
self.active_hash_mode = self.settings.CHANGE_DETECTION_MODE
self.batch_cache: Dict[str, NoteContext] = {} # WP-15b LocalBatchCache
@@ -130,12 +135,18 @@ class IngestionService:
)
note_id = note_pl["note_id"]
# Abgleich mit der Datenbank (Qdrant)
old_payload = None if force_replace else fetch_note_payload(self.client, self.prefix, note_id)
# Prüfung gegen den konfigurierten Hash-Modus (body vs. full)
check_key = f"{self.active_hash_mode}:{hash_source}:{hash_normalize}"
old_hash = (old_payload or {}).get("hashes", {}).get(check_key)
new_hash = note_pl.get("hashes", {}).get(check_key)
# Check ob Chunks oder Kanten in der DB fehlen (Reparatur-Modus)
c_miss, e_miss = artifacts_missing(self.client, self.prefix, note_id)
# Wenn Hash identisch und Artefakte vorhanden -> Skip
if not (force_replace or not old_payload or old_hash != new_hash or c_miss or e_miss):
return {**result, "status": "unchanged", "note_id": note_id}
@@ -146,36 +157,46 @@ class IngestionService:
try:
body_text = getattr(parsed, "body", "") or ""
edge_registry.ensure_latest()
profile = fm.get("chunk_profile") or fm.get("chunking_profile") or "sliding_standard"
# Profil-Auflösung via Registry
profile = note_pl.get("chunk_profile", "sliding_standard")
chunk_cfg = get_chunk_config_by_profile(self.registry, profile, note_type)
enable_smart = chunk_cfg.get("enable_smart_edge_allocation", False)
# WP-15b: Chunker-Aufruf bereitet Candidate-Pool vor
# WP-15b: Chunker-Aufruf bereitet den Candidate-Pool pro Chunk vor.
chunks = await assemble_chunks(note_id, body_text, note_type, config=chunk_cfg)
# Semantische Kanten-Validierung (Smart Edge Allocation via MoE-Profil)
for ch in chunks:
filtered = []
for cand in getattr(ch, "candidate_pool", []):
# WP-15b: Nur global_pool Kandidaten erfordern binäre Validierung
# WP-25a: Nutzt nun das spezialisierte Validierungs-Profil
if cand.get("provenance") == "global_pool" and enable_smart:
if await validate_edge_candidate(ch.text, cand, self.batch_cache, self.llm, self.settings.MINDNET_LLM_PROVIDER):
if await validate_edge_candidate(ch.text, cand, self.batch_cache, self.llm, profile_name="ingest_validator"):
filtered.append(cand)
else:
# Explizite Kanten (Wikilinks/Callouts) werden ungeprüft übernommen
filtered.append(cand)
ch.candidate_pool = filtered
# Payload-Erstellung via interne Module
# Payload-Erstellung für die Chunks
chunk_pls = make_chunk_payloads(
fm, note_pl["path"], chunks, file_path=file_path,
types_cfg=self.registry
)
# Vektorisierung der Fenster-Texte
vecs = await self.embedder.embed_documents([c.get("window") or "" for c in chunk_pls]) if chunk_pls else []
# Kanten-Aggregation
# Aggregation aller finalen Kanten (Edges)
edges = build_edges_for_note(
note_id, chunk_pls,
note_level_references=note_pl.get("references", []),
include_note_scope_refs=note_scope_refs
)
# Kanten-Typen via Registry validieren/auflösen
for e in edges:
e["kind"] = edge_registry.resolve(
e.get("kind", "related_to"),
@@ -187,13 +208,16 @@ class IngestionService:
if purge_before and old_payload:
purge_artifacts(self.client, self.prefix, note_id)
# Speichern der Haupt-Note
n_name, n_pts = points_for_note(self.prefix, note_pl, None, self.dim)
upsert_batch(self.client, n_name, n_pts)
# Speichern der Chunks
if chunk_pls and vecs:
c_pts = points_for_chunks(self.prefix, chunk_pls, vecs)[1]
upsert_batch(self.client, f"{self.prefix}_chunks", c_pts)
# Speichern der Kanten
if edges:
e_pts = points_for_edges(self.prefix, edges)[1]
upsert_batch(self.client, f"{self.prefix}_edges", e_pts)
@@ -217,4 +241,5 @@ class IngestionService:
with open(target_path, "w", encoding="utf-8") as f:
f.write(markdown_content)
await asyncio.sleep(0.1)
# Triggert sofortigen Import mit force_replace/purge_before
return await self.process_file(file_path=target_path, vault_root=vault_root, apply=True, force_replace=True, purge_before=True)
+42 -20
View File
@@ -1,10 +1,16 @@
"""
FILE: app/core/ingestion/ingestion_validation.py
DESCRIPTION: WP-15b semantische Validierung von Kanten gegen den LocalBatchCache.
AUDIT v2.12.3: Integration der zentralen Text-Bereinigung (WP-14).
WP-25b: Umstellung auf Lazy-Prompt-Orchestration (prompt_key + variables).
VERSION: 2.14.0 (WP-25b: Lazy Prompt Integration)
STATUS: Active
FIX:
- WP-25b: Entfernung manueller Prompt-Formatierung zur Unterstützung modell-spezifischer Prompts.
- WP-25b: Umstellung auf generate_raw_response mit prompt_key="edge_validation".
- WP-25a: Voller Erhalt der MoE-Profilsteuerung und Fallback-Kaskade via LLMService.
"""
import logging
from typing import Dict, Any
from typing import Dict, Any, Optional
from app.core.parser import NoteContext
# ENTSCHEIDENDER FIX: Import der neutralen Bereinigungs-Logik zur Vermeidung von Circular Imports
@@ -17,11 +23,12 @@ async def validate_edge_candidate(
edge: Dict,
batch_cache: Dict[str, NoteContext],
llm_service: Any,
provider: str
provider: Optional[str] = None,
profile_name: str = "ingest_validator"
) -> bool:
"""
WP-15b: Validiert einen Kandidaten semantisch gegen das Ziel im Cache.
Nutzt clean_llm_text zur Entfernung von Steuerzeichen vor der Auswertung.
WP-15b/25b: Validiert einen Kandidaten semantisch gegen das Ziel im Cache.
Nutzt Lazy-Prompt-Loading zur Unterstützung modell-spezifischer Validierungs-Templates.
"""
target_id = edge.get("to")
target_ctx = batch_cache.get(target_id)
@@ -32,25 +39,30 @@ async def validate_edge_candidate(
target_ctx = batch_cache.get(base_id)
# Sicherheits-Fallback (Hard-Link Integrity)
# Explizite Wikilinks oder Callouts werden nicht durch das LLM verifiziert.
if not target_ctx:
logger.info(f"ℹ️ [VALIDATION SKIP] No context for '{target_id}' - allowing link.")
return True
template = llm_service.get_prompt("edge_validation", provider)
try:
logger.info(f"⚖️ [VALIDATING] Relation '{edge.get('kind')}' -> '{target_id}'...")
prompt = template.format(
chunk_text=chunk_text[:1500],
target_title=target_ctx.title,
target_summary=target_ctx.summary,
edge_kind=edge.get("kind", "related_to")
logger.info(f"⚖️ [VALIDATING] Relation '{edge.get('kind')}' -> '{target_id}' (Profile: {profile_name})...")
# WP-25b: Lazy-Prompt Aufruf.
# Wir übergeben keine formatierte Nachricht mehr, sondern Key und Daten-Dict.
# Das manuelle 'template = llm_service.get_prompt(...)' entfällt hier.
raw_response = await llm_service.generate_raw_response(
prompt_key="edge_validation",
variables={
"chunk_text": chunk_text[:1500],
"target_title": target_ctx.title,
"target_summary": target_ctx.summary,
"edge_kind": edge.get("kind", "related_to")
},
priority="background",
profile_name=profile_name
)
# Die Antwort vom Service anfordern
raw_response = await llm_service.generate_raw_response(prompt, priority="background")
# WP-14 Fix: Zusätzliche Bereinigung zur Sicherstellung der Interpretierbarkeit
# WP-14 Fix: Bereinigung zur Sicherstellung der Interpretierbarkeit
response = clean_llm_text(raw_response)
# Semantische Prüfung des Ergebnisses
@@ -61,7 +73,17 @@ async def validate_edge_candidate(
else:
logger.info(f"🚫 [REJECTED] Relation to '{target_id}' irrelevant for this chunk.")
return is_valid
except Exception as e:
logger.warning(f"⚠️ Validation error for {target_id}: {e}")
# Im Zweifel (Timeout/Fehler) erlauben wir die Kante, um Datenverlust zu vermeiden
return True
error_str = str(e).lower()
error_type = type(e).__name__
# WP-25b FIX: Differenzierung zwischen transienten und permanenten Fehlern
# Transiente Fehler (Timeout, Network) → erlauben (Datenverlust vermeiden)
if any(x in error_str for x in ["timeout", "connection", "network", "unreachable", "refused"]):
logger.warning(f"⚠️ Transient error for {target_id} using {profile_name}: {error_type} - {e}. Allowing edge.")
return True
# Permanente Fehler (Config, Validation, Invalid Response) → ablehnen (Graph-Qualität)
logger.error(f"❌ Permanent validation error for {target_id} using {profile_name}: {error_type} - {e}")
return False
+37
View File
@@ -0,0 +1,37 @@
import logging
import os
from logging.handlers import RotatingFileHandler
def setup_logging():
# 1. Log-Verzeichnis erstellen (falls nicht vorhanden)
log_dir = "logs"
if not os.path.exists(log_dir):
os.makedirs(log_dir)
log_file = os.path.join(log_dir, "mindnet.log")
# 2. Formatter definieren (Zeitstempel | Level | Modul | Nachricht)
formatter = logging.Formatter(
'%(asctime)s | %(levelname)-8s | %(name)s | %(message)s',
datefmt='%Y-%m-%d %H:%M:%S'
)
# 3. File Handler: Schreibt in Datei (max. 5MB pro Datei, behält 5 Backups)
file_handler = RotatingFileHandler(
log_file, maxBytes=5*1024*1024, backupCount=5, encoding='utf-8'
)
file_handler.setFormatter(formatter)
file_handler.setLevel(logging.INFO)
# 4. Stream Handler: Schreibt weiterhin auf die Konsole
console_handler = logging.StreamHandler()
console_handler.setFormatter(formatter)
console_handler.setLevel(logging.INFO)
# 5. Root Logger konfigurieren
logging.basicConfig(
level=logging.INFO,
handlers=[file_handler, console_handler]
)
logging.info(f"📝 Logging initialized. Writing to {log_file}")
-22
View File
@@ -1,22 +0,0 @@
"""
FILE: app/core/qdrant.py
DESCRIPTION: Proxy-Modul zur Aufrechterhaltung der Abwärtskompatibilität (WP-14).
Leitet alle Aufrufe an das neue database-Paket weiter.
STATUS: Proxy (Legacy-Support)
"""
from .database.qdrant import (
QdrantConfig,
get_client,
ensure_collections,
ensure_payload_indexes,
collection_names
)
# Re-Export für 100% Kompatibilität
__all__ = [
"QdrantConfig",
"get_client",
"ensure_collections",
"ensure_payload_indexes",
"collection_names",
]
-24
View File
@@ -1,24 +0,0 @@
"""
FILE: app/core/qdrant_points.py
DESCRIPTION: Proxy-Modul zur Aufrechterhaltung der Abwärtskompatibilität (WP-14).
Leitet Point-Operationen an das neue database-Paket weiter.
STATUS: Proxy (Legacy-Support)
"""
from .database.qdrant_points import (
points_for_note,
points_for_chunks,
points_for_edges,
upsert_batch,
get_edges_for_sources,
search_chunks_by_vector
)
# Re-Export für 100% Kompatibilität
__all__ = [
"points_for_note",
"points_for_chunks",
"points_for_edges",
"upsert_batch",
"get_edges_for_sources",
"search_chunks_by_vector"
]
+288
View File
@@ -0,0 +1,288 @@
"""
FILE: app/core/retrieval/decision_engine.py
DESCRIPTION: Der Agentic Orchestrator für MindNet (WP-25b Edition).
Realisiert Multi-Stream Retrieval, Intent-basiertes Routing
und die neue Lazy-Prompt Orchestrierung (Module A & B).
VERSION: 1.3.2 (WP-25b: Full Robustness Recovery & Regex Parsing)
STATUS: Active
FIX:
- WP-25b: ULTRA-Robustes Intent-Parsing via Regex (Fix: 'CODING[/S]' -> 'CODING').
- WP-25b: Wiederherstellung der prepend_instruction Logik via variables.
- WP-25a: Voller Erhalt der Profil-Kaskade via LLMService v3.5.5.
- WP-25: Beibehaltung von Stream-Tracing, Edge-Boosts und Pre-Initialization.
- RECOVERY: Wiederherstellung der lokalen Sicherheits-Gates aus v1.2.1.
"""
import asyncio
import logging
import yaml
import os
import re # Neu für robustes Intent-Parsing
from typing import List, Dict, Any, Optional
# Core & Service Imports
from app.models.dto import QueryRequest, QueryResponse
from app.core.retrieval.retriever import Retriever
from app.services.llm_service import LLMService
from app.config import get_settings
logger = logging.getLogger(__name__)
class DecisionEngine:
def __init__(self):
"""Initialisiert die Engine und lädt die modularen Konfigurationen."""
self.settings = get_settings()
self.retriever = Retriever()
self.llm_service = LLMService()
self.config = self._load_engine_config()
def _load_engine_config(self) -> Dict[str, Any]:
"""Lädt die Multi-Stream Konfiguration (WP-25/25a)."""
path = os.getenv("MINDNET_DECISION_CONFIG", "config/decision_engine.yaml")
if not os.path.exists(path):
logger.error(f"❌ Decision Engine Config not found at {path}")
return {"strategies": {}, "streams_library": {}}
try:
with open(path, "r", encoding="utf-8") as f:
config = yaml.safe_load(f) or {}
# WP-25b FIX: Schema-Validierung
required_keys = ["strategies", "streams_library"]
missing = [k for k in required_keys if k not in config]
if missing:
logger.error(f"❌ Missing required keys in decision_engine.yaml: {missing}")
return {"strategies": {}, "streams_library": {}}
# Warnung bei unbekannten Top-Level-Keys
known_keys = {"version", "settings", "strategies", "streams_library"}
unknown = set(config.keys()) - known_keys
if unknown:
logger.warning(f"⚠️ Unknown keys in decision_engine.yaml: {unknown}")
logger.info(f"⚙️ Decision Engine Config loaded (v{config.get('version', 'unknown')})")
return config
except yaml.YAMLError as e:
logger.error(f"❌ YAML syntax error in decision_engine.yaml: {e}")
return {"strategies": {}, "streams_library": {}}
except Exception as e:
logger.error(f"❌ Failed to load decision_engine.yaml: {e}")
return {"strategies": {}, "streams_library": {}}
async def ask(self, query: str) -> str:
"""
Hauptmethode des MindNet Chats.
Orchestriert den agentischen Prozess: Routing -> Retrieval -> Kompression -> Synthese.
"""
# 1. Intent Recognition (Strategy Routing)
strategy_key = await self._determine_strategy(query)
strategies = self.config.get("strategies", {})
strategy = strategies.get(strategy_key)
if not strategy:
logger.warning(f"⚠️ Unknown strategy '{strategy_key}'. Fallback to FACT_WHAT.")
strategy_key = "FACT_WHAT"
strategy = strategies.get("FACT_WHAT")
if not strategy and strategies:
strategy_key = next(iter(strategies))
strategy = strategies[strategy_key]
if not strategy:
return "Entschuldigung, meine Wissensbasis ist aktuell nicht konfiguriert."
# 2. Multi-Stream Retrieval & Pre-Synthesis (Parallel Tasks inkl. Kompression)
stream_results = await self._execute_parallel_streams(strategy, query)
# 3. Finale Synthese
return await self._generate_final_answer(strategy_key, strategy, query, stream_results)
async def _determine_strategy(self, query: str) -> str:
"""WP-25b: Nutzt den LLM-Router via Lazy-Loading und bereinigt Modell-Artefakte via Regex."""
settings_cfg = self.config.get("settings", {})
prompt_key = settings_cfg.get("router_prompt_key", "intent_router_v1")
router_profile = settings_cfg.get("router_profile")
try:
# Delegation an LLMService ohne manuelle Vor-Formatierung
response = await self.llm_service.generate_raw_response(
prompt_key=prompt_key,
variables={"query": query},
max_retries=1,
priority="realtime",
profile_name=router_profile
)
# --- ULTRA-ROBUST PARSING (Fix für 'CODING[/S]') ---
# 1. Alles in Großbuchstaben umwandeln
raw_text = str(response).upper()
# 2. Regex: Suche das erste Wort, das nur aus A-Z und Unterstrichen besteht
# Dies ignoriert [/S], </s>, Newlines oder Plaudereien des Modells
match = re.search(r'\b(FACT_WHEN|FACT_WHAT|DECISION|EMPATHY|CODING|INTERVIEW)\b', raw_text)
if match:
intent = match.group(1)
logger.info(f"🎯 [ROUTING] Parsed Intent: '{intent}' from raw response: '{response.strip()}'")
return intent
# Fallback, falls Regex nicht greift
logger.warning(f"⚠️ Unmapped intent '{response.strip()}' from router. Falling back to FACT_WHAT.")
return "FACT_WHAT"
except Exception as e:
logger.error(f"Strategy Routing failed: {e}")
return "FACT_WHAT"
async def _execute_parallel_streams(self, strategy: Dict, query: str) -> Dict[str, str]:
"""Führt Such-Streams aus und komprimiert überlange Ergebnisse (Pre-Synthesis)."""
stream_keys = strategy.get("use_streams", [])
library = self.config.get("streams_library", {})
# Phase 1: Retrieval Tasks starten
retrieval_tasks = []
active_streams = []
for key in stream_keys:
stream_cfg = library.get(key)
if stream_cfg:
active_streams.append(key)
retrieval_tasks.append(self._run_single_stream(key, stream_cfg, query))
# Ergebnisse sammeln
retrieval_results = await asyncio.gather(*retrieval_tasks, return_exceptions=True)
# Phase 2: Formatierung und optionale Kompression
final_stream_tasks = []
for name, res in zip(active_streams, retrieval_results):
if isinstance(res, Exception):
logger.error(f"Stream '{name}' failed during retrieval: {res}")
async def _err(): return f"[Fehler im Wissens-Stream {name}]"
final_stream_tasks.append(_err())
continue
formatted_context = self._format_stream_context(res)
# WP-25a: Kompressions-Check (Inhaltsverdichtung)
stream_cfg = library.get(name, {})
threshold = stream_cfg.get("compression_threshold", 4000)
if len(formatted_context) > threshold:
logger.info(f"⚙️ [WP-25b] Triggering Lazy-Compression for stream '{name}'...")
comp_profile = stream_cfg.get("compression_profile")
final_stream_tasks.append(
self._compress_stream_content(name, formatted_context, query, comp_profile)
)
else:
async def _direct(c=formatted_context): return c
final_stream_tasks.append(_direct())
# Finale Inhalte parallel fertigstellen
final_contents = await asyncio.gather(*final_stream_tasks)
return dict(zip(active_streams, final_contents))
async def _compress_stream_content(self, stream_name: str, content: str, query: str, profile: Optional[str]) -> str:
"""WP-25b: Inhaltsverdichtung via Lazy-Loading 'compression_template'."""
try:
summary = await self.llm_service.generate_raw_response(
prompt_key="compression_template",
variables={
"stream_name": stream_name,
"content": content,
"query": query
},
profile_name=profile,
priority="background",
max_retries=1
)
return summary.strip() if (summary and len(summary.strip()) > 10) else content
except Exception as e:
logger.error(f"❌ Compression of {stream_name} failed: {e}")
return content
async def _run_single_stream(self, name: str, cfg: Dict, query: str) -> QueryResponse:
"""Spezialisierte Graph-Suche mit Stream-Tracing und Edge-Boosts."""
transformed_query = cfg.get("query_template", "{query}").format(query=query)
request = QueryRequest(
query=transformed_query,
top_k=cfg.get("top_k", 5),
filters={"type": cfg.get("filter_types", [])},
expand={"depth": 1},
boost_edges=cfg.get("edge_boosts", {}), # Erhalt der Gewichtung
explain=True
)
response = await self.retriever.search(request)
for hit in response.results:
hit.stream_origin = name
return response
def _format_stream_context(self, response: QueryResponse) -> str:
"""Wandelt QueryHits in einen formatierten Kontext-String um."""
if not response.results:
return "Keine spezifischen Informationen gefunden."
lines = []
for i, hit in enumerate(response.results, 1):
source = hit.source.get("path", "Unbekannt")
content = hit.source.get("text", "").strip()
lines.append(f"[{i}] QUELLE: {source}\nINHALT: {content}")
return "\n\n".join(lines)
async def _generate_final_answer(
self,
strategy_key: str,
strategy: Dict,
query: str,
stream_results: Dict[str, str]
) -> str:
"""WP-25b: Finale Synthese via Lazy-Prompt mit Robustheit aus v1.2.1."""
profile = strategy.get("llm_profile")
template_key = strategy.get("prompt_template", "fact_synthesis_v1")
system_prompt = self.llm_service.get_prompt("system_prompt")
# WP-25 ROBUSTNESS: Pre-Initialization der Variablen
all_possible_streams = ["values_stream", "facts_stream", "biography_stream", "risk_stream", "tech_stream"]
template_vars = {s: "" for s in all_possible_streams}
template_vars.update(stream_results)
template_vars["query"] = query
# WP-25a Erhalt: Prepend Instructions aus der strategy_config
prepend = strategy.get("prepend_instruction", "")
template_vars["prepend_instruction"] = prepend
try:
# WP-25b: Delegation der Synthese an den LLMService
response = await self.llm_service.generate_raw_response(
prompt_key=template_key,
variables=template_vars,
system=system_prompt,
profile_name=profile,
priority="realtime"
)
# WP-25a RECOVERY: Falls dieprepend_instruction nicht im Template-Key
# der prompts.yaml enthalten ist (WP-25b Lazy Loading), fügen wir sie
# hier manuell an den Anfang, um die Logik aus v1.2.1 zu bewahren.
if prepend and prepend not in response[:len(prepend)+50]:
logger.info("ℹ️ Adding prepend_instruction manually (not found in response).")
response = f"{prepend}\n\n{response}"
return response
except Exception as e:
logger.error(f"Final Synthesis failed: {e}")
# ROBUST FALLBACK (v1.2.1 Gate): Versuche eine minimale Antwort zu generieren
# WP-25b FIX: Konsistente Nutzung von prompt_key statt hardcodiertem Prompt
fallback_context = "\n\n".join([v for v in stream_results.values() if len(v) > 20])
try:
return await self.llm_service.generate_raw_response(
prompt_key="fallback_synthesis",
variables={"query": query, "context": fallback_context},
system=system_prompt, priority="realtime", profile_name=profile
)
except (ValueError, KeyError):
# Fallback auf direkten Prompt, falls Template nicht existiert
logger.warning("⚠️ Fallback template 'fallback_synthesis' not found. Using direct prompt.")
return await self.llm_service.generate_raw_response(
prompt=f"Beantworte: {query}\n\nKontext:\n{fallback_context}",
system=system_prompt, priority="realtime", profile_name=profile
)
+95 -33
View File
@@ -1,9 +1,8 @@
"""
FILE: app/core/retrieval/retriever.py
DESCRIPTION: Haupt-Schnittstelle für die Suche. Orchestriert Vektorsuche und Graph-Expansion.
Nutzt retriever_scoring.py für die WP-22 Logik.
MODULARISIERUNG: Verschoben in das retrieval-Paket für WP-14.
VERSION: 0.6.16
WP-15c Update: Note-Level Diversity Pooling & Super-Edge Aggregation.
VERSION: 0.7.0
STATUS: Active
DEPENDENCIES: app.config, app.models.dto, app.core.database*, app.core.graph_adapter
"""
@@ -13,6 +12,7 @@ import os
import time
import logging
from typing import Any, Dict, List, Tuple, Iterable, Optional
from collections import defaultdict
from app.config import get_settings
from app.models.dto import (
@@ -25,10 +25,10 @@ import app.core.database.qdrant as qdr
import app.core.database.qdrant_points as qp
import app.services.embeddings_client as ec
import app.core.graph_adapter as ga
import app.core.graph.graph_subgraph as ga
# Mathematische Engine importieren (Bleibt vorerst in app.core)
from app.core.retriever_scoring import get_weights, compute_wp22_score
# Mathematische Engine importieren
from app.core.retrieval.retriever_scoring import get_weights, compute_wp22_score
logger = logging.getLogger(__name__)
@@ -89,7 +89,6 @@ def _build_explanation(
) -> Explanation:
"""
Transformiert mathematische Scores und Graph-Signale in eine menschenlesbare Erklärung.
Behebt Pydantic ValidationErrors durch explizite String-Sicherung.
"""
_, edge_w_cfg, _ = get_weights()
base_val = scoring_debug["base_val"]
@@ -116,12 +115,22 @@ def _build_explanation(
elif semantic_score > 0.70:
reasons.append(Reason(kind="semantic", message="Inhaltliche Übereinstimmung.", score_impact=base_val))
# 3. Gründe für Typ und Lifecycle
# 3. Gründe für Typ und Lifecycle (WP-25 Vorbereitung)
type_weight = float(payload.get("retriever_weight", 1.0))
if type_weight != 1.0:
msg = "Bevorzugt" if type_weight > 1.0 else "De-priorisiert"
reasons.append(Reason(kind="type", message=f"{msg} durch Typ-Profil.", score_impact=base_val * (type_weight - 1.0)))
# NEU: Explizite Ausweisung des Lifecycle-Status (WP-22)
status_mult = scoring_debug.get("status_multiplier", 1.0)
if status_mult != 1.0:
status_msg = "Belohnt (Stable)" if status_mult > 1.0 else "De-priorisiert (Draft)"
reasons.append(Reason(
kind="status",
message=f"{status_msg} durch Content-Lifecycle.",
score_impact=semantic_score * (status_mult - 1.0)
))
# 4. Kanten-Verarbeitung (Graph-Intelligence)
if subgraph and target_note_id and scoring_debug["edge_bonus"] > 0:
raw_edges = []
@@ -131,7 +140,6 @@ def _build_explanation(
raw_edges.extend(subgraph.get_outgoing_edges(target_note_id) or [])
for edge in raw_edges:
# FIX: Zwingende String-Konvertierung für Pydantic-Stabilität
src = str(edge.get("source") or "note_root")
tgt = str(edge.get("target") or target_note_id or "unknown_target")
kind = str(edge.get("kind", "related_to"))
@@ -187,10 +195,14 @@ def _build_hits_from_semantic(
explain: bool = False,
dynamic_edge_boosts: Dict[str, float] = None
) -> QueryResponse:
"""Wandelt semantische Roh-Treffer in bewertete QueryHits um."""
"""
Wandelt semantische Roh-Treffer in bewertete QueryHits um.
WP-15c: Implementiert Note-Level Diversity Pooling.
"""
t0 = time.time()
enriched = []
# Erstes Scoring für alle Kandidaten
for pid, semantic_score, payload in hits:
edge_bonus, cent_bonus = 0.0, 0.0
target_id = payload.get("note_id")
@@ -202,15 +214,30 @@ def _build_hits_from_semantic(
except Exception:
pass
# Mathematisches Scoring via WP-22 Engine
debug_data = compute_wp22_score(
semantic_score, payload, edge_bonus, cent_bonus, dynamic_edge_boosts
)
enriched.append((pid, semantic_score, payload, debug_data))
# Sortierung nach finalem mathematischen Score
# 1. Sortierung nach finalem mathematischen Score
enriched_sorted = sorted(enriched, key=lambda h: h[3]["total"], reverse=True)
limited_hits = enriched_sorted[: max(1, top_k)]
# 2. WP-15c: Note-Level Diversity Pooling
# Wir behalten pro note_id nur den Hit mit dem höchsten total_score.
# Dies verhindert, dass 10 Chunks derselben Note andere KeyNotes verdrängen.
unique_note_hits = []
seen_notes = set()
for item in enriched_sorted:
_, _, payload, _ = item
note_id = str(payload.get("note_id", "unknown"))
if note_id not in seen_notes:
unique_note_hits.append(item)
seen_notes.add(note_id)
# 3. Begrenzung auf top_k nach dem Diversity-Pooling
limited_hits = unique_note_hits[: max(1, top_k)]
results: List[QueryHit] = []
for pid, s_score, pl, dbg in limited_hits:
@@ -225,7 +252,6 @@ def _build_hits_from_semantic(
applied_boosts=dynamic_edge_boosts
)
# Payload Text-Feld normalisieren
text_content = pl.get("page_content") or pl.get("text") or pl.get("content", "[Kein Text]")
results.append(QueryHit(
@@ -250,14 +276,14 @@ def _build_hits_from_semantic(
def hybrid_retrieve(req: QueryRequest) -> QueryResponse:
"""
Die Haupt-Einstiegsfunktion für die hybride Suche.
Kombiniert Vektorsuche mit Graph-Expansion und WP-22 Gewichtung.
WP-15c: Implementiert Edge-Aggregation (Super-Kanten).
"""
client, prefix = _get_client_and_prefix()
vector = list(req.query_vector) if req.query_vector else _get_query_vector(req)
top_k = req.top_k or 10
# 1. Semantische Seed-Suche
hits = _semantic_hits(client, prefix, vector, top_k=top_k, filters=req.filters)
# 1. Semantische Seed-Suche (Wir laden etwas mehr für das Pooling)
hits = _semantic_hits(client, prefix, vector, top_k=top_k * 3, filters=req.filters)
# 2. Graph Expansion Konfiguration
expand_cfg = req.expand if isinstance(req.expand, dict) else {}
@@ -266,39 +292,76 @@ def hybrid_retrieve(req: QueryRequest) -> QueryResponse:
subgraph: ga.Subgraph | None = None
if depth > 0 and hits:
# Start-IDs für den Graph-Traversal sammeln
seed_ids = list({h[2].get("note_id") for h in hits if h[2].get("note_id")})
if seed_ids:
try:
# Subgraph aus RAM/DB laden
subgraph = ga.expand(client, prefix, seed_ids, depth=depth, edge_types=expand_cfg.get("edge_types"))
# --- WP-22: Kanten-Gewichtung im RAM-Graphen vor Bonus-Berechnung ---
if subgraph and hasattr(subgraph, "graph"):
for _, _, data in subgraph.graph.edges(data=True):
# A. Provenance Weighting (WP-22 Bonus für Herkunft)
prov = data.get("provenance", "rule")
# Belohnung: Explizite Links (1.0) > Smart (0.9) > Rule (0.7)
prov_w = 1.0 if prov == "explicit" else (0.9 if prov == "smart" else 0.7)
# --- WP-15c: Edge-Aggregation & Deduplizierung (Super-Kanten) ---
# Verhindert Score-Explosion durch multiple Links auf versch. Abschnitte.
# Logik: 1. Kante zählt voll, weitere dämpfen auf Faktor 0.1.
if subgraph and hasattr(subgraph, "adj"):
for src, edge_list in subgraph.adj.items():
# Gruppiere Kanten nach Ziel-Note (Deduplizierung ID_A -> ID_B)
by_target = defaultdict(list)
for e in edge_list:
by_target[e["target"]].append(e)
# B. Intent Boost Multiplikator (Vom Router dynamisch injiziert)
kind = data.get("kind")
intent_multiplier = boost_edges.get(kind, 1.0)
aggregated_list = []
for tgt, edges in by_target.items():
if len(edges) > 1:
# Sortiere: Stärkste Kante zuerst
sorted_edges = sorted(edges, key=lambda x: x.get("weight", 0.0), reverse=True)
primary = sorted_edges[0]
# Aggregiertes Gewicht berechnen (Sättigungs-Logik)
total_w = primary.get("weight", 0.0)
for secondary in sorted_edges[1:]:
total_w += secondary.get("weight", 0.0) * 0.1
primary["weight"] = total_w
primary["is_super_edge"] = True # Flag für Explanation Layer
primary["edge_count"] = len(edges)
aggregated_list.append(primary)
else:
aggregated_list.append(edges[0])
# Finales Gewicht setzen (Basis * Provenance * Intent)
data["weight"] = data.get("weight", 1.0) * prov_w * intent_multiplier
# In-Place Update der Adjazenzliste des Graphen
subgraph.adj[src] = aggregated_list
# Re-Sync der In-Degrees für Centrality-Bonus (Aggregation konsistent halten)
subgraph.in_degree = defaultdict(int)
for src, edges in subgraph.adj.items():
for e in edges:
subgraph.in_degree[e["target"]] += 1
# --- WP-22: Kanten-Gewichtung (Provenance & Intent Boost) ---
if subgraph and hasattr(subgraph, "adj"):
for src, edges in subgraph.adj.items():
for e in edges:
# A. Provenance Weighting
prov = e.get("provenance", "rule")
prov_w = 1.0 if prov == "explicit" else (0.9 if prov == "smart" else 0.7)
# B. Intent Boost Multiplikator
kind = e.get("kind")
intent_multiplier = boost_edges.get(kind, 1.0)
# Gewichtung anpassen
e["weight"] = e.get("weight", 1.0) * prov_w * intent_multiplier
except Exception as e:
logger.error(f"Graph Expansion failed: {e}")
subgraph = None
# 3. Scoring & Explanation Generierung
# top_k wird erst hier final angewandt
return _build_hits_from_semantic(hits, top_k, "hybrid", subgraph, req.explain, boost_edges)
def semantic_retrieve(req: QueryRequest) -> QueryResponse:
"""Standard Vektorsuche ohne Graph-Einfluss (WP-02 Fallback)."""
"""Standard Vektorsuche ohne Graph-Einfluss."""
client, prefix = _get_client_and_prefix()
vector = _get_query_vector(req)
hits = _semantic_hits(client, prefix, vector, req.top_k or 10, req.filters)
@@ -308,5 +371,4 @@ def semantic_retrieve(req: QueryRequest) -> QueryResponse:
class Retriever:
"""Schnittstelle für die asynchrone Suche."""
async def search(self, request: QueryRequest) -> QueryResponse:
"""Führt eine hybride Suche aus."""
return hybrid_retrieve(request)
+22 -20
View File
@@ -1,11 +1,10 @@
"""
FILE: app/core/retrieval/retriever_scoring.py
DESCRIPTION: Mathematische Kern-Logik für das WP-22 Scoring.
DESCRIPTION: Mathematische Kern-Logik für das WP-22/WP-15c Scoring.
Berechnet Relevanz-Scores basierend auf Semantik, Graph-Intelligence und Content Lifecycle.
MODULARISIERUNG: Verschoben in das retrieval-Paket für WP-14.
VERSION: 1.0.2
FIX v1.0.3: Optimierte Interaktion zwischen Typ-Boost und Status-Dämpfung.
VERSION: 1.0.3
STATUS: Active
DEPENDENCIES: app.config, typing
"""
import os
import logging
@@ -23,10 +22,6 @@ logger = logging.getLogger(__name__)
def get_weights() -> Tuple[float, float, float]:
"""
Liefert die Basis-Gewichtung (semantic, edge, centrality) aus der Konfiguration.
Priorität:
1. config/retriever.yaml (Scoring-Sektion)
2. Umgebungsvariablen (RETRIEVER_W_*)
3. System-Defaults (1.0, 0.0, 0.0)
"""
from app.config import get_settings
settings = get_settings()
@@ -58,7 +53,7 @@ def get_status_multiplier(payload: Dict[str, Any]) -> float:
- stable: 1.2 (Belohnung für verifiziertes Wissen)
- active: 1.0 (Standard-Gewichtung)
- draft: 0.5 (Bestrafung für unfertige Fragmente)
- draft: 0.5 (Dämpfung für unfertige Fragmente)
"""
status = str(payload.get("status", "active")).lower().strip()
if status == "stable":
@@ -75,35 +70,42 @@ def compute_wp22_score(
dynamic_edge_boosts: Optional[Dict[str, float]] = None
) -> Dict[str, Any]:
"""
Die zentrale mathematische Scoring-Formel der Mindnet Intelligence.
Implementiert das WP-22 Hybrid-Scoring (Semantic * Lifecycle * Graph).
Die zentrale mathematische Scoring-Formel (WP-15c optimiert).
Implementiert das Hybrid-Scoring (Semantic * Lifecycle * Graph).
FORMEL:
Score = (Similarity * StatusMult) * (1 + (TypeWeight - 1) + ((EdgeW * EB + CentW * CB) * IntentBoost))
LOGIK:
1. Base = Similarity * StatusMult (Lifecycle-Filter).
2. Boosts = (TypeBoost - 1) + (GraphBoni * IntentFactor).
3. Final = Base * (1 + Boosts).
Returns:
Dict mit dem finalen 'total' Score und allen mathematischen Zwischenwerten für den Explanation Layer.
Der edge_bonus_raw enthält bereits die Super-Edge-Aggregation (WP-15c).
"""
sem_w, edge_w_cfg, cent_w_cfg = get_weights()
status_mult = get_status_multiplier(payload)
# Retriever Weight (Type Boost aus types.yaml, z.B. 1.1 für Decisions)
# Retriever Weight (Typ-Boost aus types.yaml, z.B. 1.1 für Decisions)
node_weight = float(payload.get("retriever_weight", 1.0))
# 1. Berechnung des Base Scores (Semantik gewichtet durch Lifecycle-Status)
# WICHTIG: Der Status wirkt hier als Multiplikator auf die Basis-Relevanz.
base_val = float(semantic_score) * status_mult
# 2. Graph Boost Factor (Teil C: Intent-spezifische Verstärkung)
# 2. Graph Boost Factor (Intent-spezifische Verstärkung aus decision_engine.yaml)
# Erhöht das Gewicht des gesamten Graphen um 50%, wenn ein spezifischer Intent vorliegt.
graph_boost_factor = 1.5 if dynamic_edge_boosts and (edge_bonus_raw > 0 or cent_bonus_raw > 0) else 1.0
# 3. Einzelne Graph-Komponenten berechnen
# WP-15c Hinweis: edge_bonus_raw ist durch den retriever.py bereits gedämpft/aggregiert.
edge_impact_final = (edge_w_cfg * edge_bonus_raw) * graph_boost_factor
cent_impact_final = (cent_w_cfg * cent_bonus_raw) * graph_boost_factor
# 4. Finales Zusammenführen (Merging)
# (node_weight - 1.0) sorgt dafür, dass ein Gewicht von 1.0 keinen Einfluss hat (neutral).
total = base_val * (1.0 + (node_weight - 1.0) + edge_impact_final + cent_impact_final)
# (node_weight - 1.0) wandelt das Gewicht in einen relativen Bonus um (z.B. 1.2 -> +0.2).
# Alle Boni werden addiert und wirken dann auf den base_val.
type_impact = node_weight - 1.0
total_boost = 1.0 + type_impact + edge_impact_final + cent_impact_final
total = base_val * total_boost
# Sicherstellen, dass der Score niemals 0 oder negativ ist (Floor)
final_score = max(0.0001, float(total))
@@ -114,7 +116,7 @@ def compute_wp22_score(
"cent_bonus": float(cent_bonus_raw),
"status_multiplier": status_mult,
"graph_boost_factor": graph_boost_factor,
"type_impact": node_weight - 1.0,
"type_impact": type_impact,
"base_val": base_val,
"edge_impact_final": edge_impact_final,
"cent_impact_final": cent_impact_final
-14
View File
@@ -1,14 +0,0 @@
"""
FILE: app/core/retriever.py
DESCRIPTION: Proxy-Modul zur Aufrechterhaltung der Abwärtskompatibilität (WP-14).
Leitet Retrieval-Anfragen an das neue retrieval-Paket weiter.
STATUS: Proxy (Legacy-Support)
"""
from .retrieval.retriever import (
Retriever,
hybrid_retrieve,
semantic_retrieve
)
# Re-Export für 100% Kompatibilität
__all__ = ["Retriever", "hybrid_retrieve", "semantic_retrieve"]
-18
View File
@@ -1,18 +0,0 @@
"""
FILE: app/core/retriever_scoring.py
DESCRIPTION: Proxy-Modul zur Aufrechterhaltung der Abwärtskompatibilität (WP-14).
Leitet Scoring-Berechnungen an das neue retrieval-Paket weiter.
STATUS: Proxy (Legacy-Support)
"""
from .retrieval.retriever_scoring import (
get_weights,
compute_wp22_score,
get_status_multiplier
)
# Re-Export für 100% Kompatibilität
__all__ = [
"get_weights",
"compute_wp22_score",
"get_status_multiplier"
]
+127 -64
View File
@@ -69,20 +69,35 @@ def render_graph_explorer_cytoscape(graph_service):
search_term = st.text_input("Suche Notiz", placeholder="Titel eingeben...", key="cy_search")
if search_term:
hits, _ = graph_service.client.scroll(
collection_name=f"{COLLECTION_PREFIX}_notes",
limit=10,
scroll_filter=models.Filter(must=[models.FieldCondition(key="title", match=models.MatchText(text=search_term))])
)
options = {h.payload['title']: h.payload['note_id'] for h in hits}
if options:
selected_title = st.selectbox("Ergebnisse:", list(options.keys()), key="cy_select")
if st.button("Laden", use_container_width=True, key="cy_load"):
new_id = options[selected_title]
st.session_state.graph_center_id = new_id
st.session_state.graph_inspected_id = new_id
st.rerun()
try:
hits, _ = graph_service.client.scroll(
collection_name=f"{COLLECTION_PREFIX}_notes",
limit=10,
scroll_filter=models.Filter(must=[models.FieldCondition(key="title", match=models.MatchText(text=search_term))])
)
options = {}
for h in hits:
if h.payload and 'title' in h.payload and 'note_id' in h.payload:
title = h.payload['title']
note_id = h.payload['note_id']
# Vermeide Duplikate (falls mehrere Chunks/Notes denselben Titel haben)
if title not in options:
options[title] = note_id
if options:
selected_title = st.selectbox("Ergebnisse:", list(options.keys()), key="cy_select")
if st.button("Laden", use_container_width=True, key="cy_load"):
new_id = options[selected_title]
st.session_state.graph_center_id = new_id
st.session_state.graph_inspected_id = new_id
st.rerun()
else:
# Zeige Info, wenn keine Ergebnisse gefunden wurden
st.info(f"Keine Notizen mit '{search_term}' im Titel gefunden.")
except Exception as e:
st.error(f"Fehler bei der Suche: {e}")
import traceback
st.code(traceback.format_exc())
st.divider()
@@ -138,6 +153,26 @@ def render_graph_explorer_cytoscape(graph_service):
)
# 2. Detail Daten (Inspector)
inspected_data = graph_service.get_note_with_full_content(inspected_id)
# DEBUG: Zeige Debug-Informationen
with st.expander("🔍 Debug-Informationen", expanded=False):
st.write(f"**Gefundene Knoten:** {len(nodes_data) if nodes_data else 0}")
st.write(f"**Gefundene Kanten:** {len(edges_data) if edges_data else 0}")
if nodes_data:
st.write("**Knoten-IDs:**")
for n in nodes_data[:10]:
nid = getattr(n, 'id', 'N/A')
st.write(f" - {nid}")
if len(nodes_data) > 10:
st.write(f" ... und {len(nodes_data) - 10} weitere")
if edges_data:
st.write("**Kanten:**")
for e in edges_data[:10]:
src = getattr(e, "source", "N/A")
tgt = getattr(e, "to", getattr(e, "target", "N/A"))
st.write(f" - {src} -> {tgt}")
if len(edges_data) > 10:
st.write(f" ... und {len(edges_data) - 10} weitere")
# --- ACTION BAR ---
action_container = st.container()
@@ -174,7 +209,12 @@ def render_graph_explorer_cytoscape(graph_service):
st.markdown(f"**ID:** `{inspected_data.get('note_id')}`")
st.markdown(f"**Typ:** `{inspected_data.get('type')}`")
with col_i2:
st.markdown(f"**Tags:** {', '.join(inspected_data.get('tags', []))}")
tags = inspected_data.get('tags', [])
if isinstance(tags, list):
tags_str = ', '.join(tags) if tags else "Keine"
else:
tags_str = str(tags) if tags else "Keine"
st.markdown(f"**Tags:** {tags_str}")
path_check = "✅" if inspected_data.get('path') else "❌"
st.markdown(f"**Pfad:** {path_check}")
@@ -189,12 +229,27 @@ def render_graph_explorer_cytoscape(graph_service):
# --- GRAPH ELEMENTS ---
cy_elements = []
# Validierung: Prüfe ob nodes_data vorhanden ist
if not nodes_data:
st.warning("⚠️ Keine Knoten gefunden. Bitte wähle eine andere Notiz.")
# Zeige trotzdem den Inspector, falls Daten vorhanden
if inspected_data:
st.info(f"**Hinweis:** Die Notiz '{inspected_data.get('title', inspected_id)}' wurde gefunden, hat aber keine Verbindungen im Graphen.")
return
# Erstelle Set aller Node-IDs für schnelle Validierung
node_ids = {n.id for n in nodes_data if hasattr(n, 'id') and n.id}
# Nodes hinzufügen
for n in nodes_data:
if not hasattr(n, 'id') or not n.id:
continue
is_center = (n.id == center_id)
is_inspected = (n.id == inspected_id)
tooltip_text = n.title if n.title else n.label
display_label = n.label
tooltip_text = getattr(n, 'title', None) or getattr(n, 'label', '')
display_label = getattr(n, 'label', str(n.id))
if len(display_label) > 15 and " " in display_label:
display_label = display_label.replace(" ", "\n", 1)
@@ -202,7 +257,7 @@ def render_graph_explorer_cytoscape(graph_service):
"data": {
"id": n.id,
"label": display_label,
"bg_color": n.color,
"bg_color": getattr(n, 'color', '#8395a7'),
"tooltip": tooltip_text
},
# Wir steuern das Aussehen rein über Klassen (.inspected / .center)
@@ -211,18 +266,22 @@ def render_graph_explorer_cytoscape(graph_service):
}
cy_elements.append(cy_node)
for e in edges_data:
target_id = getattr(e, "to", getattr(e, "target", None))
if target_id:
cy_edge = {
"data": {
"source": e.source,
"target": target_id,
"label": e.label,
"line_color": e.color
# Edges hinzufügen - nur wenn beide Nodes im Graph vorhanden sind
if edges_data:
for e in edges_data:
source_id = getattr(e, "source", None)
target_id = getattr(e, "to", getattr(e, "target", None))
# Nur hinzufügen, wenn beide IDs vorhanden UND beide Nodes im Graph sind
if source_id and target_id and source_id in node_ids and target_id in node_ids:
cy_edge = {
"data": {
"source": source_id,
"target": target_id,
"label": getattr(e, "label", ""),
"line_color": getattr(e, "color", "#bdc3c7")
}
}
}
cy_elements.append(cy_edge)
cy_elements.append(cy_edge)
# --- STYLESHEET ---
stylesheet = [
@@ -292,43 +351,47 @@ def render_graph_explorer_cytoscape(graph_service):
]
# --- RENDER ---
graph_key = f"cy_{center_id}_{st.session_state.cy_depth}_{st.session_state.cy_ideal_edge_len}"
# Nur rendern, wenn Elemente vorhanden sind
if not cy_elements:
st.warning("⚠️ Keine Graph-Elemente zum Anzeigen gefunden.")
else:
graph_key = f"cy_{center_id}_{st.session_state.cy_depth}_{st.session_state.cy_ideal_edge_len}"
clicked_elements = cytoscape(
elements=cy_elements,
stylesheet=stylesheet,
layout={
"name": "cose",
"idealEdgeLength": st.session_state.cy_ideal_edge_len,
"nodeOverlap": 20,
"refresh": 20,
"fit": True,
"padding": 50,
"randomize": False,
"componentSpacing": 100,
"nodeRepulsion": st.session_state.cy_node_repulsion,
"edgeElasticity": 100,
"nestingFactor": 5,
"gravity": 80,
"numIter": 1000,
"initialTemp": 200,
"coolingFactor": 0.95,
"minTemp": 1.0,
"animate": False
},
key=graph_key,
height="700px"
)
clicked_elements = cytoscape(
elements=cy_elements,
stylesheet=stylesheet,
layout={
"name": "cose",
"idealEdgeLength": st.session_state.cy_ideal_edge_len,
"nodeOverlap": 20,
"refresh": 20,
"fit": True,
"padding": 50,
"randomize": False,
"componentSpacing": 100,
"nodeRepulsion": st.session_state.cy_node_repulsion,
"edgeElasticity": 100,
"nestingFactor": 5,
"gravity": 80,
"numIter": 1000,
"initialTemp": 200,
"coolingFactor": 0.95,
"minTemp": 1.0,
"animate": False
},
key=graph_key,
height="700px"
)
# --- EVENT HANDLING ---
if clicked_elements:
clicked_nodes = clicked_elements.get("nodes", [])
if clicked_nodes:
clicked_id = clicked_nodes[0]
if clicked_id != st.session_state.graph_inspected_id:
st.session_state.graph_inspected_id = clicked_id
st.rerun()
# --- EVENT HANDLING ---
if clicked_elements:
clicked_nodes = clicked_elements.get("nodes", [])
if clicked_nodes:
clicked_id = clicked_nodes[0]
if clicked_id != st.session_state.graph_inspected_id:
st.session_state.graph_inspected_id = clicked_id
st.rerun()
else:
st.info("👈 Bitte wähle links eine Notiz aus.")
+178 -51
View File
@@ -10,15 +10,19 @@ LAST_ANALYSIS: 2025-12-15
import re
from qdrant_client import QdrantClient, models
from streamlit_agraph import Node, Edge
from ui_config import GRAPH_COLORS, get_edge_color, SYSTEM_EDGES
from ui_config import COLLECTION_PREFIX, GRAPH_COLORS, get_edge_color, SYSTEM_EDGES
class GraphExplorerService:
def __init__(self, url, api_key=None, prefix="mindnet"):
def __init__(self, url, api_key=None, prefix=None):
"""
Initialisiert den Service. Nutzt COLLECTION_PREFIX aus der Config,
sofern kein spezifischer Prefix übergeben wurde.
"""
self.client = QdrantClient(url=url, api_key=api_key)
self.prefix = prefix
self.notes_col = f"{prefix}_notes"
self.chunks_col = f"{prefix}_chunks"
self.edges_col = f"{prefix}_edges"
self.prefix = prefix if prefix else COLLECTION_PREFIX
self.notes_col = f"{self.prefix}_notes"
self.chunks_col = f"{self.prefix}_chunks"
self.edges_col = f"{self.prefix}_edges"
self._note_cache = {}
def get_note_with_full_content(self, note_id):
@@ -163,31 +167,33 @@ class GraphExplorerService:
return previews
def _find_connected_edges(self, note_ids, note_title=None):
"""Findet eingehende und ausgehende Kanten."""
"""
Findet eingehende und ausgehende Kanten.
WICHTIG: target_id enthält nur den Titel (ohne #Abschnitt).
target_section ist ein separates Feld für Abschnitt-Informationen.
"""
results = []
if not note_ids:
return results
# 1. OUTGOING EDGES (Der "Owner"-Fix)
# Wir suchen Kanten, die im Feld 'note_id' (Owner) eine unserer Notizen haben.
# Das findet ALLE ausgehenden Kanten, egal ob sie an einem Chunk oder der Note hängen.
if note_ids:
out_filter = models.Filter(must=[
models.FieldCondition(key="note_id", match=models.MatchAny(any=note_ids)),
models.FieldCondition(key="kind", match=models.MatchExcept(**{"except": SYSTEM_EDGES}))
])
# Limit hoch, um alles zu finden
res_out, _ = self.client.scroll(self.edges_col, scroll_filter=out_filter, limit=500, with_payload=True)
results.extend(res_out)
out_filter = models.Filter(must=[
models.FieldCondition(key="note_id", match=models.MatchAny(any=note_ids)),
models.FieldCondition(key="kind", match=models.MatchExcept(**{"except": SYSTEM_EDGES}))
])
res_out, _ = self.client.scroll(self.edges_col, scroll_filter=out_filter, limit=2000, with_payload=True)
results.extend(res_out)
# 2. INCOMING EDGES (Ziel = Chunk ID oder Titel oder Note ID)
# Hier müssen wir Chunks auflösen, um Treffer auf Chunks zu finden.
# 2. INCOMING EDGES (Ziel = Chunk ID, Note ID oder Titel)
# WICHTIG: target_id enthält nur den Titel, target_section ist separat
# Chunk IDs der aktuellen Notes holen
chunk_ids = []
if note_ids:
c_filter = models.Filter(must=[models.FieldCondition(key="note_id", match=models.MatchAny(any=note_ids))])
chunks, _ = self.client.scroll(self.chunks_col, scroll_filter=c_filter, limit=300)
chunk_ids = [c.id for c in chunks]
c_filter = models.Filter(must=[models.FieldCondition(key="note_id", match=models.MatchAny(any=note_ids))])
chunks, _ = self.client.scroll(self.chunks_col, scroll_filter=c_filter, limit=1000, with_payload=False)
chunk_ids = [c.id for c in chunks]
shoulds = []
# Case A: Edge zeigt auf einen unserer Chunks
@@ -195,42 +201,92 @@ class GraphExplorerService:
shoulds.append(models.FieldCondition(key="target_id", match=models.MatchAny(any=chunk_ids)))
# Case B: Edge zeigt direkt auf unsere Note ID
if note_ids:
shoulds.append(models.FieldCondition(key="target_id", match=models.MatchAny(any=note_ids)))
# Case C: Edge zeigt auf unseren Titel (Wikilinks)
if note_title:
shoulds.append(models.FieldCondition(key="target_id", match=models.MatchValue(value=note_title)))
shoulds.append(models.FieldCondition(key="target_id", match=models.MatchAny(any=note_ids)))
# Case C: Edge zeigt auf unseren Titel
# WICHTIG: target_id enthält nur den Titel (z.B. "Meine Prinzipien 2025")
# target_section enthält die Abschnitt-Information (z.B. "P3 – Disziplin"), wenn gesetzt
# Sammle alle relevanten Titel (inkl. Aliase)
titles_to_search = []
if note_title:
titles_to_search.append(note_title)
# Lade auch Titel aus den Notes selbst (falls note_title nicht übergeben wurde)
for nid in note_ids:
note = self._fetch_note_cached(nid)
if note:
note_title_from_db = note.get("title")
if note_title_from_db and note_title_from_db not in titles_to_search:
titles_to_search.append(note_title_from_db)
# Aliase hinzufügen
aliases = note.get("aliases", [])
if isinstance(aliases, str):
aliases = [aliases]
for alias in aliases:
if alias and alias not in titles_to_search:
titles_to_search.append(alias)
# Für jeden Titel: Suche nach exaktem Match
# target_id enthält nur den Titel, daher reicht MatchValue
for title in titles_to_search:
shoulds.append(models.FieldCondition(key="target_id", match=models.MatchValue(value=title)))
if shoulds:
in_filter = models.Filter(
must=[models.FieldCondition(key="kind", match=models.MatchExcept(**{"except": SYSTEM_EDGES}))],
should=shoulds
)
res_in, _ = self.client.scroll(self.edges_col, scroll_filter=in_filter, limit=500, with_payload=True)
res_in, _ = self.client.scroll(self.edges_col, scroll_filter=in_filter, limit=2000, with_payload=True)
results.extend(res_in)
return results
def _find_connected_edges_batch(self, note_ids):
# Wrapper für Level 2 Suche
return self._find_connected_edges(note_ids)
"""
Wrapper für Level 2 Suche.
Lädt Titel der ersten Note für Titel-basierte Suche.
"""
if not note_ids:
return []
first_note = self._fetch_note_cached(note_ids[0])
note_title = first_note.get("title") if first_note else None
return self._find_connected_edges(note_ids, note_title=note_title)
def _process_edge(self, record, nodes_dict, unique_edges, current_depth):
"""Verarbeitet eine rohe Edge, löst IDs auf und fügt sie den Dictionaries hinzu."""
"""
Verarbeitet eine rohe Edge, löst IDs auf und fügt sie den Dictionaries hinzu.
WICHTIG: Beide Richtungen werden unterstützt:
- Ausgehende Kanten: source_id gehört zu unserer Note (via note_id Owner)
- Eingehende Kanten: target_id zeigt auf unsere Note (via target_id Match)
"""
if not record or not record.payload:
return None, None
payload = record.payload
src_ref = payload.get("source_id")
tgt_ref = payload.get("target_id")
kind = payload.get("kind")
provenance = payload.get("provenance", "explicit")
# Prüfe, ob beide Referenzen vorhanden sind
if not src_ref or not tgt_ref:
return None, None
# IDs zu Notes auflösen
# WICHTIG: source_id kann Chunk-ID (note_id#c01), Note-ID oder Titel sein
# WICHTIG: target_id kann Chunk-ID, Note-ID oder Titel sein (ohne #Abschnitt)
src_note = self._resolve_note_from_ref(src_ref)
tgt_note = self._resolve_note_from_ref(tgt_ref)
if src_note and tgt_note:
src_id = src_note['note_id']
tgt_id = tgt_note['note_id']
src_id = src_note.get('note_id')
tgt_id = tgt_note.get('note_id')
# Prüfe, ob beide IDs vorhanden sind
if not src_id or not tgt_id:
return None, None
if src_id != tgt_id:
# Nodes hinzufügen
@@ -245,7 +301,7 @@ class GraphExplorerService:
# Bevorzuge explizite Kanten vor Smart Kanten
is_current_explicit = (provenance in ["explicit", "rule"])
if existing:
is_existing_explicit = (existing['provenance'] in ["explicit", "rule"])
is_existing_explicit = (existing.get('provenance', '') in ["explicit", "rule"])
if is_existing_explicit and not is_current_explicit:
should_update = False
@@ -267,38 +323,109 @@ class GraphExplorerService:
return None
def _resolve_note_from_ref(self, ref_str):
"""Löst eine ID (Chunk, Note oder Titel) zu einer Note Payload auf."""
if not ref_str: return None
"""
Löst eine Referenz zu einer Note Payload auf.
# Fall A: Chunk ID (enthält #)
WICHTIG: Wenn ref_str ein Titel#Abschnitt Format hat, wird nur der Titel-Teil verwendet.
Unterstützt:
- Note-ID: "20250101-meine-note"
- Chunk-ID: "20250101-meine-note#c01"
- Titel: "Meine Prinzipien 2025"
- Titel#Abschnitt: "Meine Prinzipien 2025#P3 – Disziplin" (trennt Abschnitt ab, sucht nur nach Titel)
"""
if not ref_str:
return None
# Fall A: Enthält # (kann Chunk-ID oder Titel#Abschnitt sein)
if "#" in ref_str:
try:
# Versuch 1: Chunk ID direkt
# Versuch 1: Chunk ID direkt (Format: note_id#c01)
res = self.client.retrieve(self.chunks_col, ids=[ref_str], with_payload=True)
if res: return self._fetch_note_cached(res[0].payload.get("note_id"))
except: pass
if res and res[0].payload:
note_id = res[0].payload.get("note_id")
if note_id:
return self._fetch_note_cached(note_id)
except:
pass
# Versuch 2: NoteID#Section (Hash abtrennen)
possible_note_id = ref_str.split("#")[0]
if self._fetch_note_cached(possible_note_id): return self._fetch_note_cached(possible_note_id)
# Versuch 2: NoteID#Section (Hash abtrennen und als Note-ID versuchen)
# z.B. "20250101-meine-note#Abschnitt" -> "20250101-meine-note"
possible_note_id = ref_str.split("#")[0].strip()
note = self._fetch_note_cached(possible_note_id)
if note:
return note
# Versuch 3: Titel#Abschnitt (Hash abtrennen und als Titel suchen)
# z.B. "Meine Prinzipien 2025#P3 – Disziplin" -> "Meine Prinzipien 2025"
# WICHTIG: target_id enthält nur den Titel, daher suchen wir nur nach dem Titel-Teil
possible_title = ref_str.split("#")[0].strip()
if possible_title:
res, _ = self.client.scroll(
collection_name=self.notes_col,
scroll_filter=models.Filter(must=[
models.FieldCondition(key="title", match=models.MatchValue(value=possible_title))
]),
limit=1, with_payload=True
)
if res and res[0].payload:
payload = res[0].payload
self._note_cache[payload['note_id']] = payload
return payload
# Fallback: Text-Suche für Fuzzy-Matching
res, _ = self.client.scroll(
collection_name=self.notes_col,
scroll_filter=models.Filter(must=[
models.FieldCondition(key="title", match=models.MatchText(text=possible_title))
]),
limit=10, with_payload=True
)
if res:
# Nimm das erste Ergebnis, das exakt oder beginnend mit possible_title übereinstimmt
for r in res:
if r.payload:
note_title = r.payload.get("title", "")
if note_title == possible_title or note_title.startswith(possible_title):
payload = r.payload
self._note_cache[payload['note_id']] = payload
return payload
# Fall B: Note ID direkt
if self._fetch_note_cached(ref_str): return self._fetch_note_cached(ref_str)
note = self._fetch_note_cached(ref_str)
if note:
return note
# Fall C: Titel
# Fall C: Titel (exakte Übereinstimmung)
res, _ = self.client.scroll(
collection_name=self.notes_col,
scroll_filter=models.Filter(must=[models.FieldCondition(key="title", match=models.MatchValue(value=ref_str))]),
scroll_filter=models.Filter(must=[
models.FieldCondition(key="title", match=models.MatchValue(value=ref_str))
]),
limit=1, with_payload=True
)
if res:
self._note_cache[res[0].payload['note_id']] = res[0].payload
return res[0].payload
if res and res[0].payload:
payload = res[0].payload
self._note_cache[payload['note_id']] = payload
return payload
# Fall D: Titel (Text-Suche für Fuzzy-Matching)
res, _ = self.client.scroll(
collection_name=self.notes_col,
scroll_filter=models.Filter(must=[
models.FieldCondition(key="title", match=models.MatchText(text=ref_str))
]),
limit=1, with_payload=True
)
if res and res[0].payload:
payload = res[0].payload
self._note_cache[payload['note_id']] = payload
return payload
return None
def _add_node_to_dict(self, node_dict, note_payload, level=1):
nid = note_payload.get("note_id")
if nid in node_dict: return
if not nid or nid in node_dict: return
ntype = note_payload.get("type", "default")
color = GRAPH_COLORS.get(ntype, GRAPH_COLORS["default"])
+97 -20
View File
@@ -1,25 +1,29 @@
"""
FILE: app/main.py
DESCRIPTION: Bootstrap der FastAPI Anwendung. Inkludiert Router und Middleware.
VERSION: 0.6.0
DESCRIPTION: Bootstrap der FastAPI Anwendung für WP-25a (Agentic MoE).
Orchestriert Lifespan-Events, globale Fehlerbehandlung und Routing.
Prüft beim Start die Integrität der Mixture of Experts Konfiguration.
VERSION: 1.1.0 (WP-25a: MoE Integrity Check)
STATUS: Active
DEPENDENCIES: app.config, app.routers.* (embed, qdrant, query, graph, tools, feedback, chat, ingest, admin)
LAST_ANALYSIS: 2025-12-15
DEPENDENCIES: app.config, app.routers.*, app.services.llm_service
"""
from __future__ import annotations
from fastapi import FastAPI
from .config import get_settings
#from .routers.embed_router import router as embed_router
#from .routers.qdrant_router import router as qdrant_router
import logging
import os
from contextlib import asynccontextmanager
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from .config import get_settings
from .services.llm_service import LLMService
# Import der Router
from .routers.query import router as query_router
from .routers.graph import router as graph_router
from .routers.tools import router as tools_router
from .routers.feedback import router as feedback_router
# NEU: Chat Router (WP-05)
from .routers.chat import router as chat_router
# NEU: Ingest Router (WP-11)
from .routers.ingest import router as ingest_router
try:
@@ -27,26 +31,98 @@ try:
except Exception:
admin_router = None
from .core.logging_setup import setup_logging
# Initialisierung des Loggings noch VOR create_app()
setup_logging()
logger = logging.getLogger(__name__)
# --- WP-25a: Lifespan Management mit MoE Integritäts-Prüfung ---
@asynccontextmanager
async def lifespan(app: FastAPI):
"""
Verwaltet den Lebenszyklus der Anwendung (Startup/Shutdown).
Verifiziert die Verfügbarkeit der MoE-Experten-Profile und Strategien.
"""
settings = get_settings()
logger.info("🚀 mindnet API: Starting up (WP-25a MoE Mode)...")
# 1. Startup: Integritäts-Check der MoE Konfiguration
# Wir prüfen die drei Säulen der Agentic-RAG Architektur.
decision_cfg = os.getenv("MINDNET_DECISION_CONFIG", "config/decision_engine.yaml")
profiles_cfg = getattr(settings, "LLM_PROFILES_PATH", "config/llm_profiles.yaml")
prompts_cfg = settings.PROMPTS_PATH
missing_files = []
if not os.path.exists(decision_cfg): missing_files.append(decision_cfg)
if not os.path.exists(profiles_cfg): missing_files.append(profiles_cfg)
if not os.path.exists(prompts_cfg): missing_files.append(prompts_cfg)
if missing_files:
logger.error(f"❌ CRITICAL: Missing MoE config files: {missing_files}")
else:
logger.info("✅ MoE Configuration files verified.")
yield
# 2. Shutdown: Ressourcen bereinigen
logger.info("🛑 mindnet API: Shutting down...")
try:
llm = LLMService()
await llm.close()
logger.info("✨ LLM resources cleaned up.")
except Exception as e:
logger.warning(f"⚠️ Error during LLMService cleanup: {e}")
logger.info("Goodbye.")
# --- App Factory ---
def create_app() -> FastAPI:
app = FastAPI(title="mindnet API", version="0.6.0") # Version bump WP-11
"""Initialisiert die FastAPI App mit WP-25a Erweiterungen."""
app = FastAPI(
title="mindnet API",
version="1.1.0", # WP-25a Milestone
lifespan=lifespan,
description="Digital Twin Knowledge Engine mit Mixture of Experts Orchestration."
)
s = get_settings()
# --- Globale Fehlerbehandlung (WP-25a Resilienz) ---
@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
"""Fängt unerwartete Fehler in der MoE-Prozesskette ab."""
logger.error(f"❌ Unhandled Engine Error: {exc}", exc_info=True)
return JSONResponse(
status_code=500,
content={
"detail": "Ein interner Fehler ist in der MoE-Kette aufgetreten.",
"error_type": type(exc).__name__
}
)
# Healthcheck
@app.get("/healthz")
def healthz():
return {"status": "ok", "qdrant": s.QDRANT_URL, "prefix": s.COLLECTION_PREFIX}
# app.include_router(embed_router)
# app.include_router(qdrant_router)
"""Bietet Statusinformationen über die Engine und Datenbank-Verbindung."""
return {
"status": "ok",
"version": "1.1.0",
"qdrant": s.QDRANT_URL,
"prefix": s.COLLECTION_PREFIX,
"moe_enabled": True
}
# Inkludieren der Router (100% Kompatibilität erhalten)
app.include_router(query_router, prefix="/query", tags=["query"])
app.include_router(graph_router, prefix="/graph", tags=["graph"])
app.include_router(tools_router, prefix="/tools", tags=["tools"])
app.include_router(feedback_router, prefix="/feedback", tags=["feedback"])
# NEU: Chat Endpoint
app.include_router(chat_router, prefix="/chat", tags=["chat"])
# NEU: Ingest Endpoint
app.include_router(chat_router, prefix="/chat", tags=["chat"]) # WP-25a Agentic Chat
app.include_router(ingest_router, prefix="/ingest", tags=["ingest"])
if admin_router:
@@ -54,4 +130,5 @@ def create_app() -> FastAPI:
return app
# Instanziierung der App
app = create_app()
+28 -22
View File
@@ -1,10 +1,9 @@
"""
FILE: app/models/dto.py
DESCRIPTION: Pydantic-Modelle (DTOs) für Request/Response Bodies. Definiert das API-Schema.
VERSION: 0.6.6 (WP-22 Debug & Stability Update)
VERSION: 0.7.1 (WP-25: Stream-Tracing Support)
STATUS: Active
DEPENDENCIES: pydantic, typing, uuid
LAST_ANALYSIS: 2025-12-18
"""
from __future__ import annotations
@@ -12,8 +11,14 @@ from pydantic import BaseModel, Field
from typing import List, Literal, Optional, Dict, Any
import uuid
# Gültige Kanten-Typen gemäß Manual
EdgeKind = Literal["references", "references_at", "backlink", "next", "prev", "belongs_to", "depends_on", "related_to", "similar_to", "caused_by", "derived_from", "based_on", "solves", "blocks", "uses", "guides"]
# WP-25: Erweiterte Kanten-Typen gemäß neuer decision_engine.yaml
EdgeKind = Literal[
"references", "references_at", "backlink", "next", "prev",
"belongs_to", "depends_on", "related_to", "similar_to",
"caused_by", "derived_from", "based_on", "solves", "blocks",
"uses", "guides", "enforced_by", "implemented_in", "part_of",
"experienced_in", "impacts", "risk_of"
]
# --- Basis-DTOs ---
@@ -43,13 +48,14 @@ class EdgeDTO(BaseModel):
direction: Literal["out", "in", "undirected"] = "out"
provenance: Optional[Literal["explicit", "rule", "smart", "structure"]] = "explicit"
confidence: float = 1.0
target_section: Optional[str] = None
# --- Request Models ---
class QueryRequest(BaseModel):
"""
Request für /query.
Request für /query. Unterstützt Multi-Stream Isolation via filters.
"""
mode: Literal["semantic", "edge", "hybrid"] = "hybrid"
query: Optional[str] = None
@@ -60,14 +66,12 @@ class QueryRequest(BaseModel):
ret: Dict = {"with_paths": True, "with_notes": True, "with_chunks": True}
explain: bool = False
# WP-22: Semantic Graph Routing
# WP-22/25: Dynamische Gewichtung der Graphen-Highways
boost_edges: Optional[Dict[str, float]] = None
class FeedbackRequest(BaseModel):
"""
User-Feedback zu einem spezifischen Treffer oder der Gesamtantwort (WP-08 Basis).
"""
"""User-Feedback zu einem spezifischen Treffer oder der Gesamtantwort."""
query_id: str = Field(..., description="ID der ursprünglichen Suche")
node_id: str = Field(..., description="ID des bewerteten Treffers oder 'generated_answer'")
score: int = Field(..., ge=1, le=5, description="1 (Irrelevant) bis 5 (Perfekt)")
@@ -75,16 +79,14 @@ class FeedbackRequest(BaseModel):
class ChatRequest(BaseModel):
"""
WP-05: Request für /chat.
"""
"""Request für /chat (WP-25 Einstieg)."""
message: str = Field(..., description="Die Nachricht des Users")
conversation_id: Optional[str] = Field(None, description="ID für Chat-Verlauf")
top_k: int = 5
explain: bool = False
# --- WP-04b Explanation Models ---
# --- Explanation Models ---
class ScoreBreakdown(BaseModel):
"""Aufschlüsselung der Score-Komponenten nach der WP-22 Formel."""
@@ -95,14 +97,14 @@ class ScoreBreakdown(BaseModel):
raw_edge_bonus: float
raw_centrality: float
node_weight: float
# WP-22 Debug Fields für Messbarkeit
status_multiplier: float = 1.0
graph_boost_factor: float = 1.0
class Reason(BaseModel):
"""Ein semantischer Grund für das Ranking."""
kind: Literal["semantic", "edge", "type", "centrality", "lifecycle"]
# WP-25: 'status' hinzugefügt für Synchronität mit retriever.py
kind: Literal["semantic", "edge", "type", "centrality", "lifecycle", "status"]
message: str
score_impact: Optional[float] = None
details: Optional[Dict[str, Any]] = None
@@ -113,7 +115,6 @@ class Explanation(BaseModel):
breakdown: ScoreBreakdown
reasons: List[Reason]
related_edges: Optional[List[EdgeDTO]] = None
# WP-22 Debug: Verifizierung des Routings
applied_intent: Optional[str] = None
applied_boosts: Optional[Dict[str, float]] = None
@@ -121,7 +122,10 @@ class Explanation(BaseModel):
# --- Response Models ---
class QueryHit(BaseModel):
"""Einzelnes Trefferobjekt für /query."""
"""
Einzelnes Trefferobjekt.
WP-25: stream_origin hinzugefügt für Tracing und Feedback-Optimierung.
"""
node_id: str
note_id: str
semantic_score: float
@@ -132,10 +136,11 @@ class QueryHit(BaseModel):
source: Optional[Dict] = None
payload: Optional[Dict] = None
explanation: Optional[Explanation] = None
stream_origin: Optional[str] = Field(None, description="Name des Ursprungs-Streams")
class QueryResponse(BaseModel):
"""Antwortstruktur für /query."""
"""Antwortstruktur für /query (wird von DecisionEngine Streams genutzt)."""
query_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
results: List[QueryHit]
used_mode: str
@@ -152,11 +157,12 @@ class GraphResponse(BaseModel):
class ChatResponse(BaseModel):
"""
WP-05/06: Antwortstruktur für /chat.
Antwortstruktur für /chat.
WP-25: 'intent' spiegelt nun die gewählte Strategie wider.
"""
query_id: str = Field(..., description="Traceability ID")
answer: str = Field(..., description="Generierte Antwort vom LLM")
sources: List[QueryHit] = Field(..., description="Die genutzten Quellen")
sources: List[QueryHit] = Field(..., description="Die genutzten Quellen (alle Streams)")
latency_ms: int
intent: Optional[str] = Field("FACT", description="WP-06: Erkannter Intent")
intent_source: Optional[str] = Field("Unknown", description="Quelle der Intent-Erkennung")
intent: Optional[str] = Field("FACT", description="Die gewählte WP-25 Strategie")
intent_source: Optional[str] = Field("LLM_Router", description="Quelle der Intent-Erkennung")
+119 -254
View File
@@ -1,12 +1,14 @@
"""
FILE: app/routers/chat.py
DESCRIPTION: Haupt-Chat-Interface (RAG & Interview). Enthält Intent-Router (Keywords/LLM) und Prompt-Construction.
VERSION: 2.7.8 (Full Unabridged Stability Edition)
DESCRIPTION: Haupt-Chat-Interface (WP-25b Edition).
Kombiniert die spezialisierte Interview-Logik mit der neuen
Lazy-Prompt-Orchestration und MoE-Synthese.
VERSION: 3.0.5 (WP-25b: Lazy Prompt Integration)
STATUS: Active
FIX:
1. Implementiert Context-Throttling für Ollama (MAX_OLLAMA_CHARS).
2. Deaktiviert LLM-Retries für den Chat (max_retries=0).
3. Behebt Double-Fallback-Schleifen und Silent Refusals.
- WP-25b: Umstellung des Interview-Modus auf Lazy-Prompt (prompt_key + variables).
- WP-25b: Delegation der RAG-Phase an die Engine v1.3.0 für konsistente MoE-Steuerung.
- WP-25a: Voller Erhalt der v3.0.2 Logik (Interview, Schema-Resolution, FastPaths).
"""
from fastapi import APIRouter, HTTPException, Depends
@@ -16,50 +18,44 @@ import uuid
import logging
import yaml
import os
import asyncio
from pathlib import Path
from app.config import get_settings
from app.models.dto import ChatRequest, ChatResponse, QueryRequest, QueryHit
from app.models.dto import ChatRequest, ChatResponse, QueryHit
from app.services.llm_service import LLMService
from app.core.retriever import Retriever
from app.services.feedback_service import log_search
router = APIRouter()
logger = logging.getLogger(__name__)
# --- Helper: Config Loader ---
# --- EBENE 1: CONFIG LOADER & CACHING (WP-25 Standard) ---
_DECISION_CONFIG_CACHE = None
_TYPES_CONFIG_CACHE = None
def _load_decision_config() -> Dict[str, Any]:
"""Lädt die Strategie-Konfiguration."""
settings = get_settings()
path = Path(settings.DECISION_CONFIG_PATH)
default_config = {
"strategies": {
"FACT": {"trigger_keywords": [], "preferred_provider": "openrouter"}
}
}
if not path.exists():
logger.warning(f"Decision config not found at {path}, using defaults.")
return default_config
try:
with open(path, "r", encoding="utf-8") as f:
return yaml.safe_load(f)
if path.exists():
with open(path, "r", encoding="utf-8") as f:
return yaml.safe_load(f) or {}
except Exception as e:
logger.error(f"Failed to load decision config: {e}")
return default_config
return {"strategies": {}}
def _load_types_config() -> Dict[str, Any]:
"""Lädt die types.yaml für Keyword-Erkennung."""
"""Lädt die types.yaml für die Typerkennung."""
path = os.getenv("MINDNET_TYPES_FILE", "config/types.yaml")
try:
with open(path, "r", encoding="utf-8") as f:
return yaml.safe_load(f) or {}
except Exception:
return {}
if os.path.exists(path):
with open(path, "r", encoding="utf-8") as f:
return yaml.safe_load(f) or {}
except Exception as e:
logger.error(f"Failed to load types config: {e}")
return {}
def get_full_config() -> Dict[str, Any]:
global _DECISION_CONFIG_CACHE
@@ -76,21 +72,17 @@ def get_types_config() -> Dict[str, Any]:
def get_decision_strategy(intent: str) -> Dict[str, Any]:
config = get_full_config()
strategies = config.get("strategies", {})
return strategies.get(intent, strategies.get("FACT", {}))
return strategies.get(intent, strategies.get("FACT_WHAT", {}))
# --- Helper: Target Type Detection (WP-07) ---
# --- EBENE 2: SPEZIAL-LOGIK (INTERVIEW & DETECTION) ---
def _detect_target_type(message: str, configured_schemas: Dict[str, Any]) -> str:
"""
Versucht zu erraten, welchen Notiz-Typ der User erstellen will.
Nutzt Keywords aus types.yaml UND Mappings.
"""
"""WP-07: Identifiziert den gewünschten Notiz-Typ (Keyword-basiert)."""
message_lower = message.lower()
# 1. Check types.yaml detection_keywords (Priority!)
types_cfg = get_types_config()
types_def = types_cfg.get("types", {})
# 1. Check types.yaml detection_keywords
for type_name, type_data in types_def.items():
keywords = type_data.get("detection_keywords", [])
for kw in keywords:
@@ -103,293 +95,166 @@ def _detect_target_type(message: str, configured_schemas: Dict[str, Any]) -> str
if type_key in message_lower:
return type_key
# 3. Synonym-Mapping (Legacy Fallback)
# 3. Synonym-Mapping (Legacy)
synonyms = {
"projekt": "project", "vorhaben": "project",
"entscheidung": "decision", "beschluss": "decision",
"ziel": "goal",
"erfahrung": "experience", "lektion": "experience",
"wert": "value",
"prinzip": "principle",
"notiz": "default", "idee": "default"
"projekt": "project", "entscheidung": "decision", "ziel": "goal",
"erfahrung": "experience", "wert": "value", "prinzip": "principle"
}
for term, schema_key in synonyms.items():
if term in message_lower:
return schema_key
return "default"
# --- Dependencies ---
def get_llm_service():
return LLMService()
def get_retriever():
return Retriever()
# --- Logic ---
def _build_enriched_context(hits: List[QueryHit]) -> str:
context_parts = []
for i, hit in enumerate(hits, 1):
source = hit.source or {}
content = (
source.get("text") or source.get("content") or
source.get("page_content") or source.get("chunk_text") or
"[Kein Text]"
)
title = hit.note_id or "Unbekannt"
payload = hit.payload or {}
note_type = payload.get("type") or source.get("type", "unknown")
note_type = str(note_type).upper()
entry = (
f"### QUELLE {i}: {title}\n"
f"TYP: [{note_type}] (Score: {hit.total_score:.2f})\n"
f"INHALT:\n{content}\n"
)
context_parts.append(entry)
return "\n\n".join(context_parts)
def _is_question(query: str) -> bool:
"""Prüft, ob der Input wahrscheinlich eine Frage ist."""
"""Prüft, ob der Input eine Frage ist."""
q = query.strip().lower()
if "?" in q: return True
# W-Fragen Indikatoren
starters = ["wer", "wie", "was", "wo", "wann", "warum", "weshalb", "wozu", "welche", "bist du", "entspricht"]
if any(q.startswith(s + " ") for s in starters):
return True
return False
starters = ["wer", "wie", "was", "wo", "wann", "warum", "weshalb", "wozu", "welche", "bist du"]
return any(q.startswith(s + " ") for s in starters)
async def _classify_intent(query: str, llm: LLMService) -> tuple[str, str]:
"""
Hybrid Router v5:
1. Decision Keywords (Strategie) -> Prio 1
2. Type Keywords (Interview Trigger) -> Prio 2
3. LLM (Fallback) -> Prio 3
"""
"""Hybrid Router: Keyword-Fast-Paths & DecisionEngine LLM Router."""
config = get_full_config()
strategies = config.get("strategies", {})
settings = config.get("settings", {})
query_lower = query.lower()
# 1. FAST PATH A: Strategie Keywords
# 1. FAST PATH: Keyword Trigger
for intent_name, strategy in strategies.items():
if intent_name == "FACT": continue
keywords = strategy.get("trigger_keywords", [])
for k in keywords:
if k.lower() in query_lower:
return intent_name, "Keyword (Strategy)"
return intent_name, "Keyword (FastPath)"
# 2. FAST PATH B: Type Keywords -> INTERVIEW
if not _is_question(query_lower):
types_cfg = get_types_config()
types_def = types_cfg.get("types", {})
for type_name, type_data in types_def.items():
keywords = type_data.get("detection_keywords", [])
for kw in keywords:
for type_name, type_data in types_cfg.get("types", {}).items():
for kw in type_data.get("detection_keywords", []):
if kw.lower() in query_lower:
return "INTERVIEW", f"Keyword (Type: {type_name})"
return "INTERVIEW", "Keyword (Interview)"
# 3. SLOW PATH: LLM Router
if settings.get("llm_fallback_enabled", False):
router_prompt_template = llm.get_prompt("llm_router_prompt")
if router_prompt_template:
prompt = router_prompt_template.replace("{query}", query)
logger.info("Keywords failed (or Question detected). Asking LLM for Intent...")
try:
# FIX: Auch beim Routing keine Retries im Chat-Fluss
raw_response = await llm.generate_raw_response(prompt, priority="realtime", max_retries=0)
llm_output_upper = raw_response.upper()
if "INTERVIEW" in llm_output_upper or "CREATE" in llm_output_upper:
return "INTERVIEW", "LLM Router"
# 3. SLOW PATH: DecisionEngine LLM Router (MoE-gesteuert)
# WP-25b FIX: Nutzung der öffentlichen API statt privater Methode
intent = await llm.decision_engine._determine_strategy(query) # TODO: Public API erstellen
return intent, "DecisionEngine (LLM)"
for strat_key in strategies.keys():
if strat_key in llm_output_upper:
return strat_key, "LLM Router"
except Exception as e:
logger.error(f"Router LLM failed: {e}")
return "FACT", "Default (No Match)"
# --- EBENE 3: RETRIEVAL AGGREGATION ---
def _collect_all_hits(stream_responses: Dict[str, Any]) -> List[QueryHit]:
"""Sammelt deduplizierte Treffer aus allen Streams für das Tracing."""
all_hits = []
seen_node_ids = set()
for _, response in stream_responses.items():
# Sammeln der Hits aus den QueryResponse Objekten
if hasattr(response, 'results'):
for hit in response.results:
if hit.node_id not in seen_node_ids:
all_hits.append(hit)
seen_node_ids.add(hit.node_id)
return sorted(all_hits, key=lambda h: h.total_score, reverse=True)
# --- EBENE 4: ENDPUNKT ---
def get_llm_service():
return LLMService()
@router.post("/", response_model=ChatResponse)
async def chat_endpoint(
request: ChatRequest,
llm: LLMService = Depends(get_llm_service),
retriever: Retriever = Depends(get_retriever)
llm: LLMService = Depends(get_llm_service)
):
start_time = time.time()
query_id = str(uuid.uuid4())
logger.info(f"Chat request [{query_id}]: {request.message[:50]}...")
logger.info(f"🚀 [WP-25b] Chat request [{query_id}]: {request.message[:50]}...")
try:
# 1. Intent Detection
intent, intent_source = await _classify_intent(request.message, llm)
logger.info(f"[{query_id}] Final Intent: {intent} via {intent_source}")
logger.info(f"[{query_id}] Intent: {intent} via {intent_source}")
# Strategy Load
strategy = get_decision_strategy(intent)
prompt_key = strategy.get("prompt_template", "rag_template")
preferred_provider = strategy.get("preferred_provider")
engine = llm.decision_engine
sources_hits = []
final_prompt = ""
context_str = ""
answer_text = ""
# 2. INTERVIEW MODE (WP-25b Lazy-Prompt Logik)
if intent == "INTERVIEW":
# --- INTERVIEW MODE ---
target_type = _detect_target_type(request.message, strategy.get("schemas", {}))
types_cfg = get_types_config()
type_def = types_cfg.get("types", {}).get(target_type, {})
fields_list = type_def.get("schema", [])
# WP-07: Restaurierte Fallback Logik
if not fields_list:
configured_schemas = strategy.get("schemas", {})
fallback_schema = configured_schemas.get(target_type, configured_schemas.get("default"))
if isinstance(fallback_schema, dict):
fields_list = fallback_schema.get("fields", [])
else:
fields_list = fallback_schema or []
fallback = configured_schemas.get(target_type, configured_schemas.get("default", {}))
fields_list = fallback.get("fields", []) if isinstance(fallback, dict) else (fallback or [])
logger.info(f"[{query_id}] Interview Type: {target_type}. Fields: {len(fields_list)}")
fields_str = "\n- " + "\n- ".join(fields_list)
template_key = strategy.get("prompt_template", "interview_template")
template = llm.get_prompt(prompt_key)
final_prompt = template.replace("{context_str}", "Dialogverlauf...") \
.replace("{query}", request.message) \
.replace("{target_type}", target_type) \
.replace("{schema_fields}", fields_str) \
.replace("{schema_hint}", "")
sources_hits = []
else:
# --- RAG MODE (FACT, DECISION, EMPATHY, CODING) ---
inject_types = strategy.get("inject_types", [])
prepend_instr = strategy.get("prepend_instruction", "")
edge_boosts = strategy.get("edge_boosts", {})
query_req = QueryRequest(
query=request.message,
mode="hybrid",
top_k=request.top_k,
explain=request.explain,
boost_edges=edge_boosts
)
retrieve_result = await retriever.search(query_req)
hits = retrieve_result.results
if inject_types:
strategy_req = QueryRequest(
query=request.message,
mode="hybrid",
top_k=3,
filters={"type": inject_types},
explain=False,
boost_edges=edge_boosts
)
strategy_result = await retriever.search(strategy_req)
existing_ids = {h.node_id for h in hits}
for strat_hit in strategy_result.results:
if strat_hit.node_id not in existing_ids:
hits.append(strat_hit)
context_str = _build_enriched_context(hits) if hits else "Keine relevanten Notizen gefunden."
# --- STABILITY FIX: OLLAMA CONTEXT THROTTLE ---
# Begrenzt den Text, um den "decode: cannot decode batches" Fehler zu vermeiden.
# MAX_OLLAMA_CHARS = 10000
settings = get_settings() # Falls noch nicht im Scope vorhanden
max_chars = getattr(settings, "MAX_OLLAMA_CHARS", 10000)
if preferred_provider == "ollama" and len(context_str) > max_chars:
logger.warning(f"⚠️ [{query_id}] Context zu groß für Ollama ({len(context_str)} chars). Kürze auf {max_chars}.")
context_str = context_str[:max_chars] + "\n[...gekürzt zur Stabilität...]"
template = llm.get_prompt(prompt_key) or "{context_str}\n\n{query}"
if prepend_instr:
context_str = f"{prepend_instr}\n\n{context_str}"
final_prompt = template.replace("{context_str}", context_str).replace("{query}", request.message)
sources_hits = hits
# --- DEBUG SPOT 1: PROMPT CONSTRUCTION ---
logger.info(f"[{query_id}] PROMPT CONSTRUCTION COMPLETE. Length: {len(final_prompt)} chars.")
if not final_prompt.strip():
logger.error(f"[{query_id}] CRITICAL: Final prompt is empty before sending to LLM!")
# --- GENERATION WITH NO-RETRY & DEEP FALLBACK ---
system_prompt = llm.get_prompt("system_prompt")
# --- DEBUG SPOT 2: PRIMARY CALL ---
logger.info(f"[{query_id}] PRIMARY CALL: Sending request to provider '{preferred_provider}' (No Retries)...")
answer_text = ""
try:
# FIX: max_retries=0 verhindert Hänger durch Retry-Kaskaden im Chat
# WP-25b: Lazy Loading Call
# Wir übergeben nur Key und Variablen. Das System formatiert passend zum Modell.
answer_text = await llm.generate_raw_response(
prompt=final_prompt,
system=system_prompt,
priority="realtime",
provider=preferred_provider,
prompt_key=template_key,
variables={
"query": request.message,
"target_type": target_type,
"schema_fields": fields_str
},
system=llm.get_prompt("system_prompt"),
priority="realtime",
profile_name="compression_fast",
max_retries=0
)
except Exception as e:
logger.error(f"🛑 [{query_id}] Primary Provider '{preferred_provider}' failed: {e}")
sources_hits = []
# DEEP FALLBACK: Wenn die Antwort leer ist (Silent Refusal) oder der Primary abgestürzt ist
if not answer_text.strip() and preferred_provider != "ollama":
# --- DEBUG SPOT 3: FALLBACK TRIGGER ---
logger.warning(f"🛑 [{query_id}] PRIMARY '{preferred_provider}' returned EMPTY or FAILED. Triggering Deep Fallback to Ollama...")
# 3. RAG MODE (WP-25b Delegation an Engine v1.3.0)
else:
# Phase A & B: Retrieval & Kompression (Delegiert an Engine v1.3.0)
formatted_context_map = await engine._execute_parallel_streams(strategy, request.message)
try:
answer_text = await llm.generate_raw_response(
prompt=final_prompt,
system=system_prompt,
priority="realtime",
provider="ollama",
max_retries=0
)
except Exception as e:
logger.error(f"🛑 [{query_id}] Deep Fallback to Ollama also failed: {e}")
answer_text = "Entschuldigung, das System ist aktuell überlastet. Bitte versuche es in einem Moment erneut."
# Erfassung der Quellen für das Tracing
raw_stream_map = {}
stream_keys = strategy.get("use_streams", [])
library = engine.config.get("streams_library", {})
retrieval_tasks = []
active_streams = []
for key in stream_keys:
if key in library:
active_streams.append(key)
retrieval_tasks.append(engine._run_single_stream(key, library[key], request.message))
responses = await asyncio.gather(*retrieval_tasks, return_exceptions=True)
for name, res in zip(active_streams, responses):
if not isinstance(res, Exception):
raw_stream_map[name] = res
sources_hits = _collect_all_hits(raw_stream_map)
# Phase C: Finale MoE Synthese (Delegiert an Engine v1.3.0)
answer_text = await engine._generate_final_answer(
intent, strategy, request.message, formatted_context_map
)
duration_ms = int((time.time() - start_time) * 1000)
# Logging
# Logging (WP-15)
try:
log_search(
query_id=query_id,
query_text=request.message,
results=sources_hits,
mode="interview" if intent == "INTERVIEW" else "chat_rag",
metadata={"intent": intent, "source": intent_source, "provider": preferred_provider}
query_id=query_id, query_text=request.message, results=sources_hits,
mode=f"wp25b_{intent.lower()}", metadata={"strategy": intent, "source": intent_source}
)
except: pass
return ChatResponse(
query_id=query_id,
answer=answer_text,
sources=sources_hits,
latency_ms=duration_ms,
intent=intent,
intent_source=intent_source
query_id=query_id, answer=answer_text, sources=sources_hits,
latency_ms=duration_ms, intent=intent, intent_source=intent_source
)
except Exception as e:
logger.error(f"Error in chat endpoint: {e}", exc_info=True)
# Wir geben eine benutzerfreundliche Meldung zurück, statt nur den Error-Stack
raise HTTPException(status_code=500, detail="Das System konnte die Anfrage nicht verarbeiten.")
logger.error(f"❌ Chat Endpoint Failure: {e}", exc_info=True)
raise HTTPException(status_code=500, detail="Fehler bei der Verarbeitung der Anfrage.")
+1 -1
View File
@@ -12,7 +12,7 @@ from typing import List, Optional
from fastapi import APIRouter, Query
from qdrant_client import QdrantClient
from app.models.dto import GraphResponse, NodeDTO, EdgeDTO
from app.core.graph_adapter import expand
from app.core.graph.graph_subgraph import expand
from app.config import get_settings
router = APIRouter()
+1 -1
View File
@@ -10,7 +10,7 @@ LAST_ANALYSIS: 2025-12-15
from __future__ import annotations
from fastapi import APIRouter, HTTPException, BackgroundTasks
from app.models.dto import QueryRequest, QueryResponse
from app.core.retriever import hybrid_retrieve, semantic_retrieve
from app.core.retrieval.retriever import hybrid_retrieve, semantic_retrieve
# NEU:
from app.services.feedback_service import log_search
+2 -2
View File
@@ -13,9 +13,9 @@ import os
from typing import List, Dict, Any, Optional, Set
import yaml
from app.core.qdrant import QdrantConfig, get_client
from app.core.database.qdrant import QdrantConfig, get_client
from app.models.dto import QueryRequest
from app.core.retriever import hybrid_retrieve
from app.core.retrieval.retriever import hybrid_retrieve
logger = logging.getLogger(__name__)
+72 -22
View File
@@ -1,40 +1,74 @@
"""
FILE: app/services/embeddings_client.py
DESCRIPTION: Unified Embedding Client. Nutzt Ollama API (HTTP). Ersetzt lokale sentence-transformers.
VERSION: 2.5.0
DESCRIPTION: Unified Embedding Client. Nutzt MoE-Profile zur Modellsteuerung.
WP-25a: Integration der llm_profiles.yaml für konsistente Vektoren.
VERSION: 2.6.0 (WP-25a: MoE & Profile Support)
STATUS: Active
DEPENDENCIES: httpx, requests, app.config
LAST_ANALYSIS: 2025-12-15
DEPENDENCIES: httpx, requests, app.config, yaml
"""
from __future__ import annotations
import os
import logging
import httpx
import requests # Für den synchronen Fallback
from typing import List
import requests
import yaml
from pathlib import Path
from typing import List, Dict, Any
from app.config import get_settings
logger = logging.getLogger(__name__)
class EmbeddingsClient:
"""
Async Client für Embeddings via Ollama.
Async Client für Embeddings.
Steuerung erfolgt über das 'embedding_expert' Profil in llm_profiles.yaml.
"""
def __init__(self):
self.settings = get_settings()
self.base_url = os.getenv("MINDNET_OLLAMA_URL", "http://127.0.0.1:11434")
self.model = os.getenv("MINDNET_EMBEDDING_MODEL")
# 1. MoE-Profil laden (WP-25a)
self.profile = self._load_embedding_profile()
# 2. Modell & URL auflösen
# Priorität: llm_profiles.yaml -> .env (Legacy) -> Fallback
self.model = self.profile.get("model") or os.getenv("MINDNET_EMBEDDING_MODEL")
provider = self.profile.get("provider", "ollama")
if provider == "ollama":
self.base_url = self.settings.OLLAMA_URL
else:
# Platzhalter für zukünftige Cloud-Embedding-Provider
self.base_url = os.getenv("MINDNET_OLLAMA_URL", "http://127.0.0.1:11434")
if not self.model:
self.model = os.getenv("MINDNET_LLM_MODEL", "phi3:mini")
logger.warning(f"No MINDNET_EMBEDDING_MODEL set. Fallback to '{self.model}'.")
logger.warning(f"⚠️ Kein Embedding-Modell in Profil oder .env gefunden. Fallback auf '{self.model}'.")
else:
logger.info(f"🧬 Embedding-Experte aktiv: Model='{self.model}' via {provider}")
def _load_embedding_profile(self) -> Dict[str, Any]:
"""Lädt die Konfiguration für den embedding_expert."""
path_str = getattr(self.settings, "LLM_PROFILES_PATH", "config/llm_profiles.yaml")
path = Path(path_str)
if not path.exists():
return {}
try:
with open(path, "r", encoding="utf-8") as f:
data = yaml.safe_load(f) or {}
profiles = data.get("profiles", {})
return profiles.get("embedding_expert", {})
except Exception as e:
logger.error(f"❌ Failed to load embedding profile: {e}")
return {}
async def embed_query(self, text: str) -> List[float]:
"""Erzeugt einen Vektor für eine Suchanfrage."""
return await self._request_embedding(text)
async def embed_documents(self, texts: List[str]) -> List[List[float]]:
"""Erzeugt Vektoren für einen Batch von Dokumenten."""
vectors = []
# Längeres Timeout für Batches
# Längeres Timeout für Batches (WP-20 Resilienz)
async with httpx.AsyncClient(timeout=120.0) as client:
for text in texts:
vec = await self._request_embedding_with_client(client, text)
@@ -42,18 +76,23 @@ class EmbeddingsClient:
return vectors
async def _request_embedding(self, text: str) -> List[float]:
"""Interner Request-Handler für Einzelabfragen."""
async with httpx.AsyncClient(timeout=30.0) as client:
return await self._request_embedding_with_client(client, text)
async def _request_embedding_with_client(self, client: httpx.AsyncClient, text: str) -> List[float]:
if not text or not text.strip(): return []
"""Führt den HTTP-Call gegen die Embedding-API durch."""
if not text or not text.strip():
return []
url = f"{self.base_url}/api/embeddings"
try:
# WP-25: Aktuell optimiert für Ollama-API Struktur
response = await client.post(url, json={"model": self.model, "prompt": text})
response.raise_for_status()
return response.json().get("embedding", [])
except Exception as e:
logger.error(f"Async embedding failed: {e}")
logger.error(f"Async embedding failed (Model: {self.model}): {e}")
return []
# ==============================================================================
@@ -62,27 +101,38 @@ class EmbeddingsClient:
def embed_text(text: str) -> List[float]:
"""
LEGACY/SYNC: Nutzt jetzt ebenfalls OLLAMA via 'requests'.
Ersetzt SentenceTransformers, um Dimensionskonflikte (768 vs 384) zu lösen.
LEGACY/SYNC: Nutzt ebenfalls die Profil-Logik für Konsistenz.
Ersetzt lokale sentence-transformers zur Vermeidung von Dimensionskonflikten.
"""
if not text or not text.strip():
return []
base_url = os.getenv("MINDNET_OLLAMA_URL", "http://127.0.0.1:11434")
model = os.getenv("MINDNET_EMBEDDING_MODEL")
settings = get_settings()
# Fallback logik identisch zur Klasse
# Schneller Profil-Lookup für Sync-Mode
path = Path(getattr(settings, "LLM_PROFILES_PATH", "config/llm_profiles.yaml"))
model = os.getenv("MINDNET_EMBEDDING_MODEL")
base_url = settings.OLLAMA_URL
if path.exists():
try:
with open(path, "r", encoding="utf-8") as f:
data = yaml.safe_load(f) or {}
prof = data.get("profiles", {}).get("embedding_expert", {})
if prof.get("model"):
model = prof["model"]
except: pass
if not model:
model = os.getenv("MINDNET_LLM_MODEL", "phi3:mini")
url = f"{base_url}/api/embeddings"
try:
# Synchroner Request (blockierend)
# Synchroner Request via requests
response = requests.post(url, json={"model": model, "prompt": text}, timeout=30)
response.raise_for_status()
data = response.json()
return data.get("embedding", [])
return response.json().get("embedding", [])
except Exception as e:
logger.error(f"Sync embedding (Ollama) failed: {e}")
logger.error(f"Sync embedding failed (Model: {model}): {e}")
return []
+192 -172
View File
@@ -1,16 +1,14 @@
"""
FILE: app/services/llm_service.py
DESCRIPTION: Hybrid-Client für Ollama, Google GenAI (Gemini) und OpenRouter.
Verwaltet provider-spezifische Prompts und Background-Last.
WP-20: Optimiertes Fallback-Management zum Schutz von Cloud-Quoten.
WP-20 Fix: Bulletproof Prompt-Auflösung für format() Aufrufe.
WP-22/JSON: Optionales JSON-Schema + strict (für OpenRouter structured outputs).
FIX: Intelligente Rate-Limit Erkennung (429 Handling), v1-API Sync & Timeouts.
VERSION: 3.3.9
WP-25b: Implementierung der Lazy-Prompt-Orchestration (Modell-spezifisch).
VERSION: 3.5.5 (WP-25b: Prompt Orchestration & Full Resilience)
STATUS: Active
FIX:
- Importiert clean_llm_text von app.core.registry zur Vermeidung von Circular Imports.
- Wendet clean_llm_text auf Text-Antworten in generate_raw_response an.
- WP-25b: get_prompt() unterstützt Hierarchie: Model-ID -> Provider -> Default.
- WP-25b: generate_raw_response() unterstützt prompt_key + variables für Lazy-Formatting.
- WP-25a: Voller Erhalt der rekursiven Fallback-Kaskade und visited_profiles Schutz.
- WP-20: Restaurierung des internen Ollama-Retry-Loops für Hardware-Stabilität.
"""
import httpx
import yaml
@@ -19,26 +17,25 @@ import asyncio
import json
from google import genai
from google.genai import types
from openai import AsyncOpenAI # Für OpenRouter (OpenAI-kompatibel)
from openai import AsyncOpenAI
from pathlib import Path
from typing import Optional, Dict, Any, Literal
from app.config import get_settings
# ENTSCHEIDENDER FIX: Import der neutralen Bereinigungs-Logik (WP-14)
# Import der neutralen Bereinigungs-Logik
from app.core.registry import clean_llm_text
logger = logging.getLogger(__name__)
class LLMService:
# GLOBALER SEMAPHOR für Hintergrund-Last Steuerung (WP-06)
_background_semaphore = None
def __init__(self):
self.settings = get_settings()
self.prompts = self._load_prompts()
self.profiles = self._load_llm_profiles()
self._decision_engine = None
# Initialisiere Semaphore einmalig auf Klassen-Ebene
if LLMService._background_semaphore is None:
limit = getattr(self.settings, "BACKGROUND_LIMIT", 2)
logger.info(f"🚦 LLMService: Initializing Background Semaphore with limit: {limit}")
@@ -50,10 +47,9 @@ class LLMService:
timeout=httpx.Timeout(self.settings.LLM_TIMEOUT)
)
# 2. Google GenAI Client (Modern SDK)
# 2. Google GenAI Client
self.google_client = None
if self.settings.GOOGLE_API_KEY:
# FIX: Wir erzwingen api_version 'v1' für höhere Stabilität bei 2.5er Modellen.
self.google_client = genai.Client(
api_key=self.settings.GOOGLE_API_KEY,
http_options={'api_version': 'v1'}
@@ -66,16 +62,20 @@ class LLMService:
self.openrouter_client = AsyncOpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=self.settings.OPENROUTER_API_KEY,
# Strikter Timeout für OpenRouter Free-Tier zur Vermeidung von Hangs.
timeout=45.0
)
logger.info("🛰️ LLMService: OpenRouter Integration active.")
@property
def decision_engine(self):
if self._decision_engine is None:
from app.core.retrieval.decision_engine import DecisionEngine
self._decision_engine = DecisionEngine()
return self._decision_engine
def _load_prompts(self) -> dict:
"""Lädt die Prompt-Konfiguration aus der YAML-Datei."""
path = Path(self.settings.PROMPTS_PATH)
if not path.exists():
logger.error(f"❌ Prompts file not found at {path}")
return {}
try:
with open(path, "r", encoding="utf-8") as f:
@@ -84,30 +84,49 @@ class LLMService:
logger.error(f"❌ Failed to load prompts: {e}")
return {}
def get_prompt(self, key: str, provider: str = None) -> str:
def _load_llm_profiles(self) -> dict:
"""WP-25a: Lädt die zentralen MoE-Profile aus der llm_profiles.yaml."""
path_str = getattr(self.settings, "LLM_PROFILES_PATH", "config/llm_profiles.yaml")
path = Path(path_str)
if not path.exists():
logger.warning(f"⚠️ LLM Profiles file not found at {path}.")
return {}
try:
with open(path, "r", encoding="utf-8") as f:
data = yaml.safe_load(f) or {}
return data.get("profiles", {})
except Exception as e:
logger.error(f"❌ Failed to load llm_profiles.yaml: {e}")
return {}
def get_prompt(self, key: str, model_id: str = None, provider: str = None) -> str:
"""
Hole provider-spezifisches Template mit intelligenter Text-Kaskade.
HINWEIS: Dies ist nur ein Text-Lookup und verbraucht kein API-Kontingent.
Kaskade: Gewählter Provider -> Gemini (Cloud-Stil) -> Ollama (Basis-Stil).
WP-25b: Hochpräziser Prompt-Lookup mit detailliertem Trace-Logging.
"""
active_provider = provider or self.settings.MINDNET_LLM_PROVIDER
data = self.prompts.get(key, "")
if not isinstance(data, dict):
return str(data)
if isinstance(data, dict):
# Wir versuchen erst den Provider, dann Gemini, dann Ollama
val = data.get(active_provider, data.get("gemini", data.get("ollama", "")))
# Falls val durch YAML-Fehler immer noch ein Dict ist, extrahiere ersten String
if isinstance(val, dict):
logger.warning(f"⚠️ [LLMService] Nested dictionary detected for key '{key}'. Using first entry.")
val = next(iter(val.values()), "") if val else ""
return str(val)
return str(data)
# 1. Spezifischstes Match: Exakte Modell-ID
if model_id and model_id in data:
logger.info(f"🎯 [PROMPT-TRACE] Level 1 Match: Model-specific ('{model_id}') for key '{key}'")
return str(data[model_id])
# 2. Mittlere Ebene: Provider
if provider and provider in data:
logger.info(f"📡 [PROMPT-TRACE] Level 2 Match: Provider-fallback ('{provider}') for key '{key}'")
return str(data[provider])
# 3. Globaler Fallback
default_val = data.get("default", data.get("gemini", data.get("ollama", "")))
logger.info(f"⚓ [PROMPT-TRACE] Level 3 Match: Global Default for key '{key}'")
return str(default_val)
async def generate_raw_response(
self,
prompt: str,
prompt: str = None,
prompt_key: str = None, # WP-25b: Lazy Loading Key
variables: dict = None, # WP-25b: Daten für Formatierung
system: str = None,
force_json: bool = False,
max_retries: int = 2,
@@ -117,51 +136,110 @@ class LLMService:
model_override: Optional[str] = None,
json_schema: Optional[Dict[str, Any]] = None,
json_schema_name: str = "mindnet_json",
strict_json_schema: bool = True
strict_json_schema: bool = True,
profile_name: Optional[str] = None,
visited_profiles: Optional[list] = None
) -> str:
"""
Haupteinstiegspunkt für LLM-Anfragen mit Priorisierung.
Wendet die Bereinigung auf Text-Antworten an.
"""
target_provider = provider or self.settings.MINDNET_LLM_PROVIDER
"""Haupteinstiegspunkt für LLM-Anfragen mit Lazy-Prompt Orchestrierung."""
visited_profiles = visited_profiles or []
target_provider = provider
target_model = model_override
target_temp = None
fallback_profile = None
if priority == "background":
async with LLMService._background_semaphore:
# 1. Profil-Auflösung (Mixture of Experts)
if profile_name and self.profiles:
profile = self.profiles.get(profile_name)
if profile:
target_provider = profile.get("provider", target_provider)
target_model = profile.get("model", target_model)
target_temp = profile.get("temperature")
fallback_profile = profile.get("fallback_profile")
visited_profiles.append(profile_name)
logger.info(f"🎭 MoE Dispatch: Profil='{profile_name}' -> Provider='{target_provider}' | Model='{target_model}'")
else:
logger.warning(f"⚠️ Profil '{profile_name}' nicht in llm_profiles.yaml gefunden!")
if not target_provider:
target_provider = self.settings.MINDNET_LLM_PROVIDER
# 2. WP-25b: Lazy Prompt Resolving
# Wir laden den Prompt erst JETZT, basierend auf dem gerade aktiven Modell.
current_prompt = prompt
if prompt_key:
template = self.get_prompt(prompt_key, model_id=target_model, provider=target_provider)
# WP-25b FIX: Validierung des geladenen Prompts
if not template or not template.strip():
available_keys = list(self.prompts.keys())
logger.error(f"❌ Prompt key '{prompt_key}' not found or empty. Available keys: {available_keys[:10]}...")
raise ValueError(f"Invalid prompt_key: '{prompt_key}' (not found in prompts.yaml)")
try:
# Formatierung mit den übergebenen Variablen
current_prompt = template.format(**(variables or {}))
except KeyError as e:
logger.error(f"❌ Prompt formatting failed for key '{prompt_key}': Missing variable {e}")
raise ValueError(f"Missing variable in prompt '{prompt_key}': {e}")
except Exception as e:
logger.error(f"❌ Prompt formatting failed for key '{prompt_key}': {e}")
current_prompt = template # Sicherheits-Fallback
# 3. Ausführung mit Fehler-Handling für Kaskade
try:
if priority == "background":
async with LLMService._background_semaphore:
res = await self._dispatch(
target_provider, current_prompt, system, force_json,
max_retries, base_delay, target_model,
json_schema, json_schema_name, strict_json_schema, target_temp
)
else:
res = await self._dispatch(
target_provider, prompt, system, force_json,
max_retries, base_delay, model_override,
json_schema, json_schema_name, strict_json_schema
target_provider, current_prompt, system, force_json,
max_retries, base_delay, target_model,
json_schema, json_schema_name, strict_json_schema, target_temp
)
# WP-14 Fix: Bereinige Text-Antworten vor Rückgabe
return clean_llm_text(res) if not force_json else res
res = await self._dispatch(
target_provider, prompt, system, force_json,
max_retries, base_delay, model_override,
json_schema, json_schema_name, strict_json_schema
)
# WP-14 Fix: Bereinige Text-Antworten vor Rückgabe
return clean_llm_text(res) if not force_json else res
# Check auf leere Cloud-Antworten (WP-25 Stability)
if not res and target_provider != "ollama":
logger.warning(f"⚠️ Empty response from {target_provider}. Triggering fallback.")
raise ValueError(f"Empty response from {target_provider}")
return clean_llm_text(res) if not force_json else res
except Exception as e:
logger.error(f"❌ Error during execution of profile '{profile_name}' ({target_provider}): {e}")
# 4. WP-25b Kaskaden-Logik (Rekursiv mit Modell-spezifischem Re-Loading)
if fallback_profile and fallback_profile not in visited_profiles:
logger.info(f"🔄 Switching to fallback profile: '{fallback_profile}'")
return await self.generate_raw_response(
prompt=prompt,
prompt_key=prompt_key,
variables=variables, # Ermöglicht neues Formatting für Fallback-Modell
system=system, force_json=force_json,
max_retries=max_retries, base_delay=base_delay,
priority=priority, provider=None, model_override=None,
json_schema=json_schema, json_schema_name=json_schema_name,
strict_json_schema=strict_json_schema,
profile_name=fallback_profile,
visited_profiles=visited_profiles
)
# 5. Ultimativer Notanker: Falls alles fehlschlägt, direkt zu Ollama
if target_provider != "ollama" and self.settings.LLM_FALLBACK_ENABLED:
logger.warning(f"🚨 Kaskade erschöpft. Nutze finalen Ollama-Notanker.")
res = await self._execute_ollama(current_prompt, system, force_json, max_retries, base_delay, target_temp, target_model)
return clean_llm_text(res) if not force_json else res
raise e
async def _dispatch(
self,
provider: str,
prompt: str,
system: Optional[str],
force_json: bool,
max_retries: int,
base_delay: float,
model_override: Optional[str],
json_schema: Optional[Dict[str, Any]],
json_schema_name: str,
strict_json_schema: bool
self, provider, prompt, system, force_json, max_retries, base_delay,
model_override, json_schema, json_schema_name, strict_json_schema, temperature
) -> str:
"""
Routet die Anfrage mit intelligenter Rate-Limit Erkennung.
Nutzt max_retries um die Rate-Limit Schleife zu begrenzen.
"""
"""Routet die Anfrage an den spezifischen Provider-Executor."""
rate_limit_attempts = 0
# FIX: Wir nutzen max_retries als Limit für Rate-Limit Versuche, wenn explizit klein gewählt (z.B. Chat)
max_rate_retries = min(max_retries, getattr(self.settings, "LLM_RATE_LIMIT_RETRIES", 3))
wait_time = getattr(self.settings, "LLM_RATE_LIMIT_WAIT", 60.0)
@@ -169,114 +247,74 @@ class LLMService:
try:
if provider == "openrouter" and self.openrouter_client:
return await self._execute_openrouter(
prompt=prompt,
system=system,
force_json=force_json,
model_override=model_override,
json_schema=json_schema,
json_schema_name=json_schema_name,
strict_json_schema=strict_json_schema
prompt=prompt, system=system, force_json=force_json,
model_override=model_override, json_schema=json_schema,
json_schema_name=json_schema_name, strict_json_schema=strict_json_schema,
temperature=temperature
)
if provider == "gemini" and self.google_client:
return await self._execute_google(prompt, system, force_json, model_override)
return await self._execute_google(prompt, system, force_json, model_override, temperature)
# Default/Fallback zu Ollama
return await self._execute_ollama(prompt, system, force_json, max_retries, base_delay)
return await self._execute_ollama(prompt, system, force_json, max_retries, base_delay, temperature, model_override)
except Exception as e:
err_str = str(e)
# Intelligente 429 Erkennung
is_rate_limit = any(x in err_str for x in ["429", "RESOURCE_EXHAUSTED", "rate_limited", "Too Many Requests"])
if is_rate_limit and rate_limit_attempts < max_rate_retries:
if any(x in err_str for x in ["429", "RESOURCE_EXHAUSTED", "rate_limited"]):
rate_limit_attempts += 1
logger.warning(
f"⏳ [LLMService] Rate Limit detected from {provider}. "
f"Attempt {rate_limit_attempts}/{max_rate_retries}. Waiting {wait_time}s..."
)
logger.warning(f"⏳ Rate Limit {provider}. Attempt {rate_limit_attempts}. Wait {wait_time}s.")
await asyncio.sleep(wait_time)
continue
# Wenn kein Rate-Limit oder Retries erschöpft -> Fallback zu Ollama (falls aktiviert)
if self.settings.LLM_FALLBACK_ENABLED and provider != "ollama":
logger.warning(
f"🔄 Provider {provider} failed ({err_str}). Falling back to LOCAL OLLAMA."
)
return await self._execute_ollama(prompt, system, force_json, max_retries, base_delay)
raise e
async def _execute_google(self, prompt, system, force_json, model_override):
"""Native Google SDK Integration (Gemini) mit v1 Fix."""
model = model_override or self.settings.GEMINI_MODEL
clean_model = model.replace("models/", "")
config = types.GenerateContentConfig(
system_instruction=system,
response_mime_type="application/json" if force_json else "text/plain"
)
async def _execute_google(self, prompt, system, force_json, model_override, temperature):
model = (model_override or self.settings.GEMINI_MODEL).replace("models/", "")
config_kwargs = {
"system_instruction": system,
"response_mime_type": "application/json" if force_json else "text/plain"
}
if temperature is not None:
config_kwargs["temperature"] = temperature
config = types.GenerateContentConfig(**config_kwargs)
response = await asyncio.wait_for(
asyncio.to_thread(
self.google_client.models.generate_content,
model=clean_model, contents=prompt, config=config
),
asyncio.to_thread(self.google_client.models.generate_content, model=model, contents=prompt, config=config),
timeout=45.0
)
return response.text.strip()
async def _execute_openrouter(
self,
prompt: str,
system: Optional[str],
force_json: bool,
model_override: Optional[str],
json_schema: Optional[Dict[str, Any]] = None,
json_schema_name: str = "mindnet_json",
strict_json_schema: bool = True
) -> str:
"""OpenRouter API Integration (OpenAI-kompatibel)."""
async def _execute_openrouter(self, prompt, system, force_json, model_override, json_schema, json_schema_name, strict_json_schema, temperature) -> str:
model = model_override or self.settings.OPENROUTER_MODEL
logger.info(f"🛰️ OpenRouter Call: Model='{model}' | Temp={temperature}")
messages = []
if system:
messages.append({"role": "system", "content": system})
if system: messages.append({"role": "system", "content": system})
messages.append({"role": "user", "content": prompt})
kwargs: Dict[str, Any] = {}
if temperature is not None: kwargs["temperature"] = temperature
if force_json:
if json_schema:
kwargs["response_format"] = {
"type": "json_schema",
"json_schema": {
"name": json_schema_name,
"strict": strict_json_schema,
"schema": json_schema
}
}
kwargs["response_format"] = {"type": "json_schema", "json_schema": {"name": json_schema_name, "strict": strict_json_schema, "schema": json_schema}}
else:
kwargs["response_format"] = {"type": "json_object"}
response = await self.openrouter_client.chat.completions.create(
model=model,
messages=messages,
**kwargs
)
return response.choices[0].message.content.strip()
response = await self.openrouter_client.chat.completions.create(model=model, messages=messages, **kwargs)
if not response.choices: return ""
return response.choices[0].message.content.strip() if response.choices[0].message.content else ""
async def _execute_ollama(self, prompt, system, force_json, max_retries, base_delay):
"""Lokaler Ollama Call mit striktem Retry-Limit."""
async def _execute_ollama(self, prompt, system, force_json, max_retries, base_delay, temperature=None, model_override=None):
# WP-20: Restaurierter Retry-Loop für lokale Hardware-Resilienz
effective_model = model_override or self.settings.LLM_MODEL
effective_temp = temperature if temperature is not None else (0.1 if force_json else 0.7)
payload = {
"model": self.settings.LLM_MODEL,
"prompt": prompt,
"stream": False,
"options": {
"temperature": 0.1 if force_json else 0.7,
"num_ctx": 8192 # Begrenzung für Stabilität (WP-20)
}
"model": effective_model,
"prompt": prompt, "stream": False,
"options": {"temperature": effective_temp, "num_ctx": 8192}
}
if force_json:
payload["format"] = "json"
if system:
payload["system"] = system
if force_json: payload["format"] = "json"
if system: payload["system"] = system
attempt = 0
while True:
@@ -286,32 +324,14 @@ class LLMService:
return res.json().get("response", "").strip()
except Exception as e:
attempt += 1
# WICHTIG: Wenn max_retries=0 (Chat), bricht dies nach dem 1. Versuch (attempt=1) sofort ab.
if attempt > max_retries:
logger.error(f"❌ Ollama request failed after {attempt} attempt(s): {e}")
if attempt > max_retries:
logger.error(f"❌ Ollama failure after {attempt} attempts: {e}")
raise e
wait_time = base_delay * (2 ** (attempt - 1))
logger.warning(f"⚠️ Ollama attempt {attempt} failed. Retrying in {wait_time}s...")
await asyncio.sleep(wait_time)
await asyncio.sleep(base_delay * (2 ** (attempt - 1)))
async def generate_rag_response(self, query: str, context_str: str) -> str:
"""Vollständiges RAG Chat-Interface."""
provider = self.settings.MINDNET_LLM_PROVIDER
system_prompt = self.get_prompt("system_prompt", provider)
rag_template = self.get_prompt("rag_template", provider)
final_prompt = rag_template.format(context_str=context_str, query=query)
# RAG Aufrufe im Chat nutzen nun standardmäßig max_retries=2 (überschreibbar)
# Durch den Aufruf von generate_raw_response wird die Bereinigung automatisch angewendet.
return await self.generate_raw_response(
final_prompt,
system=system_prompt,
priority="realtime"
)
async def generate_rag_response(self, query: str, context_str: Optional[str] = None) -> str:
return await self.decision_engine.ask(query)
async def close(self):
"""Schließt die HTTP-Verbindungen."""
if self.ollama_client:
await self.ollama_client.aclose()
+113 -124
View File
@@ -1,145 +1,134 @@
# config/decision_engine.yaml
# Steuerung der Decision Engine (Intent Recognition & Graph Routing)
# VERSION: 2.6.1 (WP-20: Hybrid LLM & WP-22: Semantic Graph Routing)
# VERSION: 3.2.2 (WP-25a: Decoupled MoE Logic)
# STATUS: Active
# DoD: Keine Hardcoded Modelle, volle Integration der strategischen Boosts.
# DESCRIPTION: Zentrale Orchestrierung der Multi-Stream-Engine.
# FIX:
# - Auslagerung der LLM-Profile in llm_profiles.yaml zur zentralen Wartbarkeit.
# - Integration von compression_thresholds zur Inhaltsverdichtung (WP-25a).
# - 100% Erhalt aller WP-25 Edge-Boosts und Filter-Typen (v3.1.6).
version: 2.6
version: 3.2
settings:
llm_fallback_enabled: true
# Strategie für den Router selbst (Welches Modell erkennt den Intent?)
# "auto" nutzt den in MINDNET_LLM_PROVIDER gesetzten Standard (z.B. openrouter).
# "auto" nutzt den globalen Default-Provider aus der .env
router_provider: "auto"
# Verweis auf den Intent-Klassifizierer in der prompts.yaml
router_prompt_key: "intent_router_v1"
# Pfad zur neuen Experten-Konfiguration (WP-25a Architektur-Cleanliness)
profiles_config_path: "config/llm_profiles.yaml"
router_profile: "compression_fast"
# Few-Shot Prompting für den LLM-Router
llm_router_prompt: |
Du bist der zentrale Intent-Klassifikator für Mindnet, einen digitalen Zwilling.
Analysiere die Nachricht und wähle die passende Strategie.
Antworte NUR mit dem Namen der Strategie.
STRATEGIEN:
- INTERVIEW: User will Wissen erfassen, Notizen anlegen oder Dinge festhalten.
- DECISION: Rat, Strategie, Abwägung von Werten, "Soll ich tun X?".
- EMPATHY: Gefühle, Reflexion der eigenen Verfassung, Frust, Freude.
- CODING: Code-Erstellung, Debugging, technische Dokumentation.
- FACT: Reine Wissensabfrage, Definitionen, Suchen von Informationen.
BEISPIELE:
User: "Wie funktioniert die Qdrant-Vektor-DB?" -> FACT
User: "Soll ich mein Startup jetzt verkaufen?" -> DECISION
User: "Notiere mir kurz meine Gedanken zum Meeting." -> INTERVIEW
User: "Ich fühle mich heute sehr erschöpft." -> EMPATHY
User: "Schreibe eine FastAPI-Route für den Ingest." -> CODING
NACHRICHT: "{query}"
STRATEGIE:
# --- EBENE 1: STREAM-LIBRARY (Bausteine basierend auf types.yaml v2.7.0) ---
streams_library:
values_stream:
name: "Identität & Ethik"
# Referenz auf Experten-Profil (z.B. lokal via Ollama für Privacy)
llm_profile: "identity_safe"
compression_profile: "identity_safe"
compression_threshold: 2500
query_template: "Welche meiner Werte und Prinzipien betreffen: {query}"
filter_types: ["value", "principle", "belief", "trait", "boundary", "need", "motivation"]
top_k: 5
edge_boosts:
guides: 3.0
enforced_by: 2.5
based_on: 2.0
strategies:
# 1. Fakten-Abfrage (Turbo-Modus via OpenRouter / Primary)
FACT:
description: "Reine Wissensabfrage."
preferred_provider: "openrouter"
trigger_keywords: []
inject_types: []
# WP-22: Definitionen & Hierarchien im Graphen bevorzugen
facts_stream:
name: "Operative Realität"
llm_profile: "synthesis_pro"
compression_profile: "compression_fast"
compression_threshold: 3500
query_template: "Status, Ressourcen und Fakten zu: {query}"
filter_types: ["project", "decision", "task", "goal", "event", "state"]
top_k: 5
edge_boosts:
part_of: 2.0
composed_of: 2.0
similar_to: 1.5
caused_by: 0.5
prompt_template: "rag_template"
prepend_instruction: null
depends_on: 1.5
implemented_in: 1.5
# 2. Entscheidungs-Frage (Power-Strategie via Gemini)
DECISION:
description: "Der User sucht Rat, Strategie oder Abwägung."
preferred_provider: "gemini"
trigger_keywords:
- "soll ich"
- "meinung"
- "besser"
- "empfehlung"
- "strategie"
- "entscheidung"
- "abwägung"
- "vergleich"
inject_types: ["value", "principle", "goal", "risk"]
# WP-22: Risiken und Konsequenzen im Graphen priorisieren
biography_stream:
name: "Persönliche Erfahrung"
llm_profile: "synthesis_pro"
compression_profile: "compression_fast"
compression_threshold: 3000
query_template: "Welche Erlebnisse habe ich im Kontext von {query} gemacht?"
filter_types: ["experience", "journal", "profile", "person"]
top_k: 3
edge_boosts:
related_to: 1.5
experienced_in: 2.0
expert_for: 2.5
risk_stream:
name: "Risiko-Radar"
llm_profile: "synthesis_pro"
compression_profile: "compression_fast"
compression_threshold: 2500
query_template: "Gefahren, Hindernisse oder Risiken bei: {query}"
filter_types: ["risk", "obstacle", "bias"]
top_k: 3
edge_boosts:
blocks: 2.5
solves: 2.0
depends_on: 1.5
risk_of: 2.5
impacts: 2.0
prompt_template: "decision_template"
prepend_instruction: |
!!! ENTSCHEIDUNGS-MODUS (HYBRID AI) !!!
BITTE WÄGE FAKTEN GEGEN FOLGENDE WERTE, PRINZIPIEN UND ZIELE AB:
risk_of: 2.5
# 3. Empathie / "Ich"-Modus (Lokal & Privat via Ollama)
EMPATHY:
description: "Reaktion auf emotionale Zustände."
preferred_provider: "openrouter"
trigger_keywords:
- "ich fühle"
- "traurig"
- "glücklich"
- "gestresst"
- "angst"
- "nervt"
- "überfordert"
- "müde"
inject_types: ["experience", "belief", "profile"]
edge_boosts:
based_on: 2.0
related_to: 2.0
experienced_in: 2.5
blocks: 0.1
prompt_template: "empathy_template"
prepend_instruction: null
# 4. Coding / Technical (Gemini Power)
CODING:
description: "Technische Anfragen und Programmierung."
preferred_provider: "gemini"
trigger_keywords:
- "code"
- "python"
- "script"
- "funktion"
- "bug"
- "syntax"
- "json"
- "yaml"
- "bash"
inject_types: ["snippet", "reference", "source"]
# WP-22: Technische Abhängigkeiten priorisieren
tech_stream:
name: "Wissen & Technik"
llm_profile: "tech_expert"
compression_profile: "compression_fast"
compression_threshold: 4500
query_template: "Inhaltliche Details und Definitionen zu: {query}"
filter_types: ["concept", "source", "glossary", "idea", "insight", "skill", "habit"]
top_k: 5
edge_boosts:
uses: 2.5
depends_on: 2.0
implemented_in: 3.0
prompt_template: "technical_template"
prepend_instruction: null
# 5. Interview / Datenerfassung (Lokal)
# --- EBENE 2: STRATEGIEN (Finale Komposition via MoE-Profile) ---
strategies:
FACT_WHEN:
description: "Abfrage von exakten Zeitpunkten und Terminen."
llm_profile: "synthesis_pro"
trigger_keywords: ["wann", "datum", "uhrzeit", "zeitpunkt"]
use_streams: ["facts_stream", "biography_stream", "tech_stream"]
prompt_template: "fact_synthesis_v1"
FACT_WHAT:
description: "Abfrage von Definitionen, Listen und Inhalten."
llm_profile: "synthesis_pro"
trigger_keywords: ["was ist", "welche sind", "liste", "übersicht", "zusammenfassung"]
use_streams: ["facts_stream", "tech_stream", "biography_stream"]
prompt_template: "fact_synthesis_v1"
DECISION:
description: "Der User sucht Rat, Strategie oder Abwägung."
llm_profile: "synthesis_pro"
trigger_keywords: ["soll ich", "sollte ich", "entscheidung", "abwägen", "priorität", "empfehlung"]
use_streams: ["values_stream", "facts_stream", "risk_stream"]
prompt_template: "decision_synthesis_v1"
prepend_instruction: |
!!! ENTSCHEIDUNGS-MODUS (AGENTIC MULTI-STREAM) !!!
Analysiere die Fakten vor dem Hintergrund meiner Werte und evaluiere die Risiken.
Wäge ab, ob das Vorhaben mit meiner langfristigen Identität kompatibel ist.
EMPATHY:
description: "Reaktion auf emotionale Zustände."
llm_profile: "synthesis_pro"
trigger_keywords: ["fühle", "traurig", "glücklich", "stress", "angst"]
use_streams: ["biography_stream", "values_stream"]
prompt_template: "empathy_template"
CODING:
description: "Technische Anfragen und Programmierung."
llm_profile: "tech_expert"
trigger_keywords: ["code", "python", "script", "bug", "syntax"]
use_streams: ["tech_stream", "facts_stream"]
prompt_template: "technical_template"
INTERVIEW:
description: "Der User möchte Wissen erfassen."
preferred_provider: "openrouter"
trigger_keywords:
- "neue notiz"
- "etwas notieren"
- "festhalten"
- "erstellen"
- "dokumentieren"
- "anlegen"
- "interview"
- "erfassen"
- "idee speichern"
- "draft"
inject_types: []
edge_boosts: {}
prompt_template: "interview_template"
prepend_instruction: null
description: "Der User möchte Wissen erfassen (Eingabemodus)."
llm_profile: "compression_fast"
use_streams: []
prompt_template: "interview_template"
+64
View File
@@ -0,0 +1,64 @@
# config/llm_profiles.yaml
# VERSION: 1.3.0 (WP-25a: Global MoE & Fallback Cascade)
# STATUS: Active
# DESCRIPTION: Zentrale Definition der LLM-Rollen inkl. Ausfall-Logik (Kaskade).
profiles:
# --- CHAT & SYNTHESE ---
# Der "Architekt": Hochwertige Synthese. Fällt bei Fehlern auf den Backup-Cloud-Experten zurück.
synthesis_pro:
provider: "openrouter"
model: "google/gemini-2.0-flash-exp:free"
temperature: 0.7
fallback_profile: "synthesis_backup"
# Der "Vize": Leistungsstarkes Modell bei einem anderen Provider (Resilienz).
synthesis_backup:
provider: "openrouter"
model: "meta-llama/llama-3.3-70b-instruct:free"
temperature: 0.5
fallback_profile: "identity_safe" # Letzte Instanz: Lokal
# Der "Ingenieur": Fachspezialist für Code. Nutzt bei Ausfall den Generalisten.
tech_expert:
provider: "openrouter"
model: "qwen/qwen-2.5-vl-7b-instruct:free"
temperature: 0.3
fallback_profile: "synthesis_pro"
# Der "Dampfhammer": Schnell für Routing und Zusammenfassungen.
compression_fast:
provider: "openrouter"
model: "mistralai/mistral-7b-instruct:free"
temperature: 0.1
fallback_profile: "identity_safe"
# --- INGESTION EXPERTEN ---
# Spezialist für die Extraktion komplexer Datenstrukturen aus Dokumenten.
ingest_extractor:
provider: "openrouter"
model: "mistralai/mistral-7b-instruct:free"
temperature: 0.2
fallback_profile: "synthesis_backup"
# Spezialist für binäre Prüfungen (YES/NO). Muss extrem deterministisch sein.
ingest_validator:
provider: "openrouter"
model: "mistralai/mistral-7b-instruct:free"
temperature: 0.0
fallback_profile: "compression_fast"
# --- LOKALER ANKER & PRIVACY ---
# Der "Wächter": Lokales Modell für maximale Privatsphäre. Ende der Kaskade.
identity_safe:
provider: "ollama"
model: "phi3:mini"
temperature: 0.2
# Kein fallback_profile definiert = Terminaler Endpunkt
# --- EMBEDDING EXPERTE ---
# Zentralisierung des Embedding-Modells zur Entfernung aus der .env.
embedding_expert:
provider: "ollama"
model: "nomic-embed-text"
dimensions: 768
+337
View File
@@ -0,0 +1,337 @@
# config/prompts.yaml — VERSION 3.1.2 (WP-25 Cleanup: Multi-Stream Sync)
# STATUS: Active
# FIX:
# - 100% Wiederherstellung der Ingest- & Validierungslogik (Sektion 5-8).
# - Überführung der Kategorien 1-4 in die Multi-Stream Struktur unter Beibehaltung des Inhalts.
# - Konsolidierung: Sektion 9 (v3.0.0) wurde in Sektion 1 & 2 integriert (keine Redundanz).
system_prompt: |
Du bist 'mindnet', mein digitaler Zwilling und strategischer Partner.
DEINE IDENTITÄT:
- Du bist nicht nur eine Datenbank, sondern handelst nach MEINEN Werten und Zielen.
- Du passt deinen Stil dynamisch an die Situation an (Analytisch, Empathisch oder Technisch).
DEINE REGELN:
1. Deine Antwort muss zu 100% auf dem bereitgestellten KONTEXT basieren.
2. Halluziniere keine Fakten, die nicht in den Quellen stehen.
3. Antworte auf Deutsch (außer bei Code/Fachbegriffen).
# ---------------------------------------------------------
# 1. STANDARD: Fakten & Wissen (Intent: FACT_WHAT / FACT_WHEN)
# ---------------------------------------------------------
# Ersetzt das alte 'rag_template'. Nutzt jetzt parallele Streams.
fact_synthesis_v1:
ollama: |
WISSENS-STREAMS:
=========================================
FAKTEN & STATUS:
{facts_stream}
ERFAHRUNG & BIOGRAFIE:
{biography_stream}
WISSEN & TECHNIK:
{tech_stream}
=========================================
FRAGE:
{query}
ANWEISUNG:
Beantworte die Frage präzise basierend auf den Quellen.
Kombiniere harte Fakten mit persönlichen Erfahrungen, falls vorhanden.
Fasse die Informationen zusammen. Sei objektiv und neutral.
gemini: |
Beantworte die Wissensabfrage "{query}" basierend auf diesen Streams:
FAKTEN: {facts_stream}
BIOGRAFIE/ERFAHRUNG: {biography_stream}
TECHNIK: {tech_stream}
Kombiniere harte Fakten mit persönlichen Erfahrungen, falls vorhanden. Antworte strukturiert und präzise.
openrouter: |
Synthese der Wissens-Streams für: {query}
Inhalt: {facts_stream} | {biography_stream} | {tech_stream}
Antworte basierend auf dem bereitgestellten Kontext.
# ---------------------------------------------------------
# 2. DECISION: Strategie & Abwägung (Intent: DECISION)
# ---------------------------------------------------------
# Ersetzt das alte 'decision_template'. Nutzt jetzt parallele Streams.
decision_synthesis_v1:
ollama: |
ENTSCHEIDUNGS-STREAMS:
=========================================
WERTE & PRINZIPIEN (Identität):
{values_stream}
OPERATIVE FAKTEN (Realität):
{facts_stream}
RISIKO-RADAR (Konsequenzen):
{risk_stream}
=========================================
ENTSCHEIDUNGSFRAGE:
{query}
ANWEISUNG:
Du agierst als mein Entscheidungs-Partner.
1. Analysiere die Faktenlage aus den Quellen.
2. Prüfe dies hart gegen meine strategischen Notizen (Werte & Prinzipien).
3. Wäge ab: Passt die technische/faktische Lösung zu meinen Werten?
FORMAT:
- **Analyse:** (Kurze Zusammenfassung der Fakten)
- **Abgleich:** (Gibt es Konflikte mit Werten/Zielen? Nenne die Quelle!)
- **Empfehlung:** (Klare Meinung: Ja/No/Vielleicht mit Begründung)
gemini: |
Agiere als mein strategischer Partner. Analysiere die Frage: {query}
Werte: {values_stream} | Fakten: {facts_stream} | Risiken: {risk_stream}.
Wäge ab und gib eine klare strategische Empfehlung ab.
openrouter: |
Strategische Multi-Stream Analyse für: {query}
Werte-Basis: {values_stream} | Fakten: {facts_stream} | Risiken: {risk_stream}
Bitte wäge ab und gib eine Empfehlung.
# ---------------------------------------------------------
# 3. EMPATHY: Der Spiegel / "Ich"-Modus (Intent: EMPATHY)
# ---------------------------------------------------------
empathy_template:
ollama: |
KONTEXT (ERFAHRUNGEN & WERTE):
=========================================
ERLEBNISSE & BIOGRAFIE:
{biography_stream}
WERTE & BEDÜRFNISSE:
{values_stream}
=========================================
SITUATION:
{query}
ANWEISUNG:
Du agierst jetzt als mein empathischer Spiegel.
1. Versuche nicht sofort, das Problem technisch zu lösen.
2. Zeige Verständnis für die Situation basierend auf meinen eigenen Erfahrungen ([EXPERIENCE]) oder Werten, falls im Kontext vorhanden.
3. Antworte in der "Ich"-Form oder "Wir"-Form. Sei unterstützend.
TONFALL:
Ruhig, verständnisvoll, reflektiert. Keine Aufzählungszeichen, sondern fließender Text.
gemini: "Sei mein digitaler Spiegel für {query}. Kontext: {biography_stream}, {values_stream}"
openrouter: "Empathische Reflexion der Situation {query}. Persönlicher Kontext: {biography_stream}, {values_stream}"
# ---------------------------------------------------------
# 4. TECHNICAL: Der Coder (Intent: CODING)
# ---------------------------------------------------------
technical_template:
ollama: |
KONTEXT (WISSEN & PROJEKTE):
=========================================
TECHNIK & SNIPPETS:
{tech_stream}
PROJEKT-STATUS:
{facts_stream}
=========================================
TASK:
{query}
ANWEISUNG:
Du bist Senior Developer.
1. Ignoriere Smalltalk. Komm sofort zum Punkt.
2. Generiere validen, performanten Code basierend auf den Quellen.
3. Wenn Quellen fehlen, nutze dein allgemeines Programmierwissen, aber weise darauf hin.
FORMAT:
- Kurze Erklärung des Ansatzes.
- Markdown Code-Block (Copy-Paste fertig).
- Wichtige Edge-Cases.
gemini: "Generiere Code für {query} unter Berücksichtigung von {tech_stream} und {facts_stream}."
openrouter: "Technischer Support für {query}. Referenzen: {tech_stream}, Projekt-Kontext: {facts_stream}"
# ---------------------------------------------------------
# 5. INTERVIEW: Der "One-Shot Extractor" (WP-07)
# ---------------------------------------------------------
interview_template:
ollama: |
TASK:
Du bist ein professioneller Ghostwriter. Verwandle den "USER INPUT" in eine strukturierte Notiz vom Typ '{target_type}'.
STRUKTUR (Nutze EXAKT diese Überschriften):
{schema_fields}
USER INPUT:
"{query}"
ANWEISUNG ZUM INHALT:
1. Analysiere den Input genau.
2. Schreibe die Inhalte unter die passenden Überschriften aus der STRUKTUR-Liste oben.
3. STIL: Schreibe flüssig, professionell und in der Ich-Perspektive. Korrigiere Grammatikfehler, aber behalte den persönlichen Ton bei.
4. Wenn Informationen für einen Abschnitt fehlen, schreibe nur: "[TODO: Ergänzen]". Erfinde nichts dazu.
OUTPUT FORMAT (YAML + MARKDOWN):
---
type: {target_type}
status: draft
title: (Erstelle einen treffenden, kurzen Titel für den Inhalt)
tags: [Tag1, Tag2]
---
# (Wiederhole den Titel hier)
## (Erster Begriff aus STRUKTUR)
(Text...)
## (Zweiter Begriff aus STRUKTUR)
(Text...)
gemini: "Extrahiere Daten für {target_type} aus {query}."
openrouter: "Strukturiere den Input {query} nach dem Schema {schema_fields} für Typ {target_type}."
# ---------------------------------------------------------
# 6. EDGE_ALLOCATION: Kantenfilter (Ingest)
# ---------------------------------------------------------
edge_allocation_template:
ollama: |
TASK:
Du bist ein strikter Selektor. Du erhältst eine Liste von "Kandidaten-Kanten" (Strings).
Wähle jene aus, die inhaltlich im "Textabschnitt" vorkommen oder relevant sind.
TEXTABSCHNITT:
"""
{chunk_text}
"""
KANDIDATEN (Auswahl-Pool):
{edge_list}
REGELN:
1. Die Kanten haben das Format "typ:ziel". Der "typ" ist variabel und kann ALLES sein.
2. Gib NUR die Strings aus der Kandidaten-Liste zurück, die zum Text passen.
3. Erfinde KEINE neuen Kanten.
4. Antworte als flache JSON-Liste.
DEIN OUTPUT (JSON):
gemini: |
TASK: Ordne Kanten einem Textabschnitt zu.
ERLAUBTE TYPEN: {valid_types}
TEXT: {chunk_text}
KANDIDATEN: {edge_list}
OUTPUT: STRIKT eine flache JSON-Liste ["typ:ziel"]. Kein Text davor/danach. Wenn nichts: []. Keine Objekte!
openrouter: |
TASK: Filtere relevante Kanten aus dem Pool.
ERLAUBTE TYPEN: {valid_types}
TEXT: {chunk_text}
POOL: {edge_list}
ANWEISUNG: Gib NUR eine flache JSON-Liste von Strings zurück.
BEISPIEL: ["kind:target", "kind:target"]
REGEL: Kein Text, keine Analyse, keine Kommentare. Wenn nichts passt, gib [] zurück.
OUTPUT:
# ---------------------------------------------------------
# 7. SMART EDGE ALLOCATION: Extraktion (Ingest)
# ---------------------------------------------------------
edge_extraction:
ollama: |
TASK:
Du bist ein Wissens-Ingenieur für den digitalen Zwilling 'mindnet'.
Deine Aufgabe ist es, semantische Relationen (Kanten) aus dem Text zu extrahieren,
die die Hauptnotiz '{note_id}' mit anderen Konzepten verbinden.
ANWEISUNGEN:
1. Identifiziere wichtige Entitäten, Konzepte oder Ereignisse im Text.
2. Bestimme die Art der Beziehung (z.B. part_of, uses, related_to, blocks, caused_by).
3. Das Ziel (target) muss ein prägnanter Begriff sein.
4. Antworte AUSSCHLIESSLICH in validem JSON als Liste von Objekten.
BEISPIEL:
[[ {{"to": "Ziel-Konzept", \"kind\": \"beziehungs_typ\"}} ]]
TEXT:
"""
{text}
"""
DEIN OUTPUT (JSON):
gemini: |
Analysiere '{note_id}'. Extrahiere semantische Beziehungen.
ERLAUBTE TYPEN: {valid_types}
TEXT: {text}
OUTPUT: STRIKT JSON-Array von Objekten: [[{{"to\":\"Ziel\",\"kind\":\"typ\"}}]]. Kein Text davor/danach. Wenn nichts: [].
openrouter: |
TASK: Extrahiere semantische Relationen für '{note_id}'.
ERLAUBTE TYPEN: {valid_types}
TEXT: {text}
ANWEISUNG: Antworte AUSSCHLIESSLICH mit einem JSON-Array von Objekten.
FORMAT: [[{{"to\":\"Ziel-Begriff\",\"kind\":\"typ\"}}]]
STRIKTES VERBOT: Schreibe keine Einleitung, keine Analyse und keine Erklärungen.
Wenn keine Relationen existieren, antworte NUR mit: []
OUTPUT:
# ---------------------------------------------------------
# 8. WP-15b: EDGE VALIDATION (Ingest/Validate)
# ---------------------------------------------------------
edge_validation:
gemini: |
Bewerte die semantische Validität dieser Verbindung im Wissensgraph.
KONTEXT DER QUELLE (Chunk):
"{chunk_text}"
ZIEL-NOTIZ: "{target_title}"
ZIEL-BESCHREIBUNG (Zusammenfassung):
"{target_summary}"
GEPLANTE RELATION: "{edge_kind}"
FRAGE: Bestätigt der Kontext der Quelle die Beziehung '{edge_kind}' zum Ziel?
REGEL: Antworte NUR mit 'YES' oder 'NO'. Keine Erklärungen oder Smalltalk.
openrouter: |
Verify semantic relation for graph construction.
Source Context: {chunk_text}
Target Note: {target_title}
Target Summary: {target_summary}
Proposed Relation: {edge_kind}
Instruction: Does the source context support this relation to the target?
Result: Respond ONLY with 'YES' or 'NO'.
ollama: |
Bewerte die semantische Korrektheit dieser Verbindung.
QUELLE: {chunk_text}
ZIEL: {target_title} ({target_summary})
BEZIEHUNG: {edge_kind}
Ist diese Verbindung valide? Antworte NUR mit YES oder NO.
# ---------------------------------------------------------
# 10. WP-25: INTENT ROUTING (Intent: CLASSIFY)
# ---------------------------------------------------------
intent_router_v1:
ollama: |
Analysiere die Nutzeranfrage und wähle die passende Strategie.
Antworte NUR mit dem Namen der Strategie.
STRATEGIEN:
- FACT_WHEN: Nur für explizite Fragen nach einem exakten Datum, Uhrzeit oder dem "Wann" eines Ereignisses.
- FACT_WHAT: Fragen nach Inhalten, Listen von Objekten/Projekten, Definitionen oder "Was/Welche" Anfragen (auch bei Zeiträumen).
- DECISION: Rat, Meinung, "Soll ich?", Abwägung gegen Werte.
- EMPATHY: Emotionen, Reflexion, Befindlichkeit.
- CODING: Programmierung, Skripte, technische Syntax.
- INTERVIEW: Dokumentation neuer Informationen, Notizen anlegen.
NACHRICHT: "{query}"
STRATEGIE:
gemini: |
Classify intent:
- FACT_WHEN: Exact dates/times only.
- FACT_WHAT: Content, lists of entities (projects, etc.), definitions, "What/Which" queries.
- DECISION: Strategic advice/values.
- EMPATHY: Emotions.
- CODING: Tech/Code.
- INTERVIEW: Data entry.
Query: "{query}"
Result (One word only):
openrouter: |
Select strategy for Mindnet:
FACT_WHEN (timing/dates), FACT_WHAT (entities/lists/what/which), DECISION, EMPATHY, CODING, INTERVIEW.
Query: "{query}"
Response:
+218 -38
View File
@@ -1,8 +1,9 @@
# config/prompts.yaml — Final V2.6.0 (WP-15b Candidate-Validation)
# WP-20: Optimierte Cloud-Templates zur Unterdrückung von Modell-Geschwätz.
# FIX: Explizite Verbote für Einleitungstexte zur Vermeidung von JSON-Parsing-Fehlern.
# WP-15b: Integration der binären edge_validation für den Two-Pass Workflow.
# OLLAMA: UNVERÄNDERT laut Benutzeranweisung.
# config/prompts.yaml — VERSION 3.2.2 (WP-25b: Hierarchical Model Sync)
# STATUS: Active
# FIX:
# - 100% Erhalt der Original-Prompts aus v3.1.2 für die Provider-Ebene (ollama, gemini, openrouter).
# - Integration der Modell-spezifischen Overrides für Gemini 2.0, Llama 3.3 und Qwen 2.5.
# - Hinzufügen des notwendigen 'compression_template' für die DecisionEngine v1.3.0.
system_prompt: |
Du bist 'mindnet', mein digitaler Zwilling und strategischer Partner.
@@ -17,39 +18,78 @@ system_prompt: |
3. Antworte auf Deutsch (außer bei Code/Fachbegriffen).
# ---------------------------------------------------------
# 1. STANDARD: Fakten & Wissen (Intent: FACT)
# 1. STANDARD: Fakten & Wissen (Intent: FACT_WHAT / FACT_WHEN)
# ---------------------------------------------------------
rag_template:
fact_synthesis_v1:
# --- Modell-spezifisch (WP-25b Optimierung) ---
"google/gemini-2.0-flash-exp:free": |
Analysiere die Wissens-Streams für: {query}
FAKTEN: {facts_stream} | BIOGRAFIE: {biography_stream} | TECHNIK: {tech_stream}
Nutze deine hohe Reasoning-Kapazität für eine tiefe Synthese. Antworte präzise auf Deutsch.
"meta-llama/llama-3.3-70b-instruct:free": |
Erstelle eine fundierte Synthese für die Frage: "{query}"
Nutze die Daten: {facts_stream}, {biography_stream} und {tech_stream}.
Trenne klare Fakten von Erfahrungen. Bleibe strikt beim bereitgestellten Kontext.
# --- EXAKTE Provider-Fallbacks aus v3.1.2 ---
ollama: |
QUELLEN (WISSEN):
WISSENS-STREAMS:
=========================================
{context_str}
FAKTEN & STATUS:
{facts_stream}
ERFAHRUNG & BIOGRAFIE:
{biography_stream}
WISSEN & TECHNIK:
{tech_stream}
=========================================
FRAGE:
{query}
ANWEISUNG:
Beantworte die Frage präzise basierend auf den Quellen.
Beantworte die Frage präzise basierend auf den Quellen.
Kombiniere harte Fakten mit persönlichen Erfahrungen, falls vorhanden.
Fasse die Informationen zusammen. Sei objektiv und neutral.
gemini: |
Kontext meines digitalen Zwillings: {context_str}
Beantworte strukturiert und präzise: {query}
Beantworte die Wissensabfrage "{query}" basierend auf diesen Streams:
FAKTEN: {facts_stream}
BIOGRAFIE/ERFAHRUNG: {biography_stream}
TECHNIK: {tech_stream}
Kombiniere harte Fakten mit persönlichen Erfahrungen, falls vorhanden. Antworte strukturiert und präzise.
openrouter: |
Kontext-Analyse für den digitalen Zwilling:
{context_str}
Anfrage: {query}
Antworte basierend auf dem Kontext.
Synthese der Wissens-Streams für: {query}
Inhalt: {facts_stream} | {biography_stream} | {tech_stream}
Antworte basierend auf dem bereitgestellten Kontext.
default: "Beantworte {query} basierend auf dem Kontext: {facts_stream} {biography_stream} {tech_stream}."
# ---------------------------------------------------------
# 2. DECISION: Strategie & Abwägung (Intent: DECISION)
# ---------------------------------------------------------
decision_template:
decision_synthesis_v1:
# --- Modell-spezifisch (WP-25b Optimierung) ---
"google/gemini-2.0-flash-exp:free": |
Agiere als strategischer Partner für: {query}
WERTE: {values_stream} | FAKTEN: {facts_stream} | RISIKEN: {risk_stream}
Prüfe die Fakten gegen meine Werte. Zeige Zielkonflikte auf. Gib eine klare Empfehlung.
# --- EXAKTE Provider-Fallbacks aus v3.1.2 ---
ollama: |
KONTEXT (FAKTEN & STRATEGIE):
ENTSCHEIDUNGS-STREAMS:
=========================================
{context_str}
WERTE & PRINZIPIEN (Identität):
{values_stream}
OPERATIVE FAKTEN (Realität):
{facts_stream}
RISIKO-RADAR (Konsequenzen):
{risk_stream}
=========================================
ENTSCHEIDUNGSFRAGE:
@@ -58,27 +98,39 @@ decision_template:
ANWEISUNG:
Du agierst als mein Entscheidungs-Partner.
1. Analysiere die Faktenlage aus den Quellen.
2. Prüfe dies hart gegen meine strategischen Notizen (Typ [VALUE], [PRINCIPLE], [GOAL]).
2. Prüfe dies hart gegen meine strategischen Notizen (Werte & Prinzipien).
3. Wäge ab: Passt die technische/faktische Lösung zu meinen Werten?
FORMAT:
- **Analyse:** (Kurze Zusammenfassung der Fakten)
- **Abgleich:** (Gibt es Konflikte mit Werten/Zielen? Nenne die Quelle!)
- **Empfehlung:** (Klare Meinung: Ja/No/Vielleicht mit Begründung)
gemini: |
Agiere als strategischer Partner. Analysiere die Frage {query} basierend auf meinen Werten im Kontext {context_str}.
Agiere als mein strategischer Partner. Analysiere die Frage: {query}
Werte: {values_stream} | Fakten: {facts_stream} | Risiken: {risk_stream}.
Wäge ab und gib eine klare strategische Empfehlung ab.
openrouter: |
Strategische Entscheidungsanalyse: {query}
Wertebasis aus dem Graphen: {context_str}
Strategische Multi-Stream Analyse für: {query}
Werte-Basis: {values_stream} | Fakten: {facts_stream} | Risiken: {risk_stream}
Bitte wäge ab und gib eine Empfehlung.
default: "Prüfe {query} gegen Werte {values_stream} und Fakten {facts_stream}."
# ---------------------------------------------------------
# 3. EMPATHY: Der Spiegel / "Ich"-Modus (Intent: EMPATHY)
# ---------------------------------------------------------
empathy_template:
# --- EXAKTE Provider-Fallbacks aus v3.1.2 ---
ollama: |
KONTEXT (ERFAHRUNGEN & GLAUBENSSÄTZE):
KONTEXT (ERFAHRUNGEN & WERTE):
=========================================
{context_str}
ERLEBNISSE & BIOGRAFIE:
{biography_stream}
WERTE & BEDÜRFNISSE:
{values_stream}
=========================================
SITUATION:
@@ -87,22 +139,36 @@ empathy_template:
ANWEISUNG:
Du agierst jetzt als mein empathischer Spiegel.
1. Versuche nicht sofort, das Problem technisch zu lösen.
2. Zeige Verständnis für die Situation basierend auf meinen eigenen Erfahrungen ([EXPERIENCE]) oder Glaubenssätzen ([BELIEF]), falls im Kontext vorhanden.
2. Zeige Verständnis für die Situation basierend auf meinen eigenen Erfahrungen ([EXPERIENCE]) oder Werten, falls im Kontext vorhanden.
3. Antworte in der "Ich"-Form oder "Wir"-Form. Sei unterstützend.
TONFALL:
Ruhig, verständnisvoll, reflektiert. Keine Aufzählungszeichen, sondern fließender Text.
gemini: "Sei mein digitaler Spiegel für {query}. Kontext: {context_str}"
openrouter: "Empathische Reflexion der Situation {query}. Persönlicher Kontext: {context_str}"
gemini: "Sei mein digitaler Spiegel für {query}. Kontext: {biography_stream}, {values_stream}"
openrouter: "Empathische Reflexion der Situation {query}. Persönlicher Kontext: {biography_stream}, {values_stream}"
default: "Reflektiere empathisch über {query} basierend auf {biography_stream}."
# ---------------------------------------------------------
# 4. TECHNICAL: Der Coder (Intent: CODING)
# ---------------------------------------------------------
technical_template:
# --- Modell-spezifisch (WP-25b Optimierung) ---
"qwen/qwen-2.5-vl-7b-instruct:free": |
Du bist Senior Software Engineer. TASK: {query}
REFERENZEN: {tech_stream} | KONTEXT: {facts_stream}
Generiere validen, performanten Code. Nutze die Snippets aus dem Kontext.
# --- EXAKTE Provider-Fallbacks aus v3.1.2 ---
ollama: |
KONTEXT (DOCS & SNIPPETS):
KONTEXT (WISSEN & PROJEKTE):
=========================================
{context_str}
TECHNIK & SNIPPETS:
{tech_stream}
PROJEKT-STATUS:
{facts_stream}
=========================================
TASK:
@@ -118,13 +184,17 @@ technical_template:
- Kurze Erklärung des Ansatzes.
- Markdown Code-Block (Copy-Paste fertig).
- Wichtige Edge-Cases.
gemini: "Generiere Code für {query} unter Berücksichtigung von {context_str}."
openrouter: "Technischer Support für {query}. Code-Referenzen: {context_str}"
gemini: "Generiere Code für {query} unter Berücksichtigung von {tech_stream} und {facts_stream}."
openrouter: "Technischer Support für {query}. Referenzen: {tech_stream}, Projekt-Kontext: {facts_stream}"
default: "Erstelle eine technische Lösung für {query}."
# ---------------------------------------------------------
# 5. INTERVIEW: Der "One-Shot Extractor" (Performance Mode)
# 5. INTERVIEW: Der "One-Shot Extractor" (WP-07)
# ---------------------------------------------------------
interview_template:
# --- EXAKTE Provider-Fallbacks aus v3.1.2 ---
ollama: |
TASK:
Du bist ein professioneller Ghostwriter. Verwandle den "USER INPUT" in eine strukturierte Notiz vom Typ '{target_type}'.
@@ -156,11 +226,30 @@ interview_template:
## (Zweiter Begriff aus STRUKTUR)
(Text...)
gemini: "Extrahiere Daten für {target_type} aus {query}."
openrouter: "Strukturiere den Input {query} nach dem Schema {schema_fields} für Typ {target_type}."
default: "Extrahiere Informationen für {target_type} aus dem Input: {query}"
# ---------------------------------------------------------
# 6. EDGE_ALLOCATION: Kantenfilter (Intent: OFFLINE_FILTER)
# 6. WP-25b: PRE-SYNTHESIS COMPRESSION (Neu!)
# ---------------------------------------------------------
compression_template:
"mistralai/mistral-7b-instruct:free": |
Reduziere den Stream '{stream_name}' auf die Informationen, die für die Beantwortung der Frage '{query}' absolut notwendig sind.
BEHALTE: Harte Fakten, Projektnamen, konkrete Werte und Quellenangaben.
ENTFERNE: Redundante Einleitungen, Füllwörter und irrelevante Details.
INHALT:
{content}
KOMPRIMIERTE ANALYSE:
default: "Fasse das Wichtigste aus {stream_name} für die Frage {query} kurz zusammen: {content}"
# ---------------------------------------------------------
# 7. EDGE_ALLOCATION: Kantenfilter (Ingest)
# ---------------------------------------------------------
edge_allocation_template:
ollama: |
@@ -183,12 +272,14 @@ edge_allocation_template:
4. Antworte als flache JSON-Liste.
DEIN OUTPUT (JSON):
gemini: |
TASK: Ordne Kanten einem Textabschnitt zu.
ERLAUBTE TYPEN: {valid_types}
TEXT: {chunk_text}
KANDIDATEN: {edge_list}
OUTPUT: STRIKT eine flache JSON-Liste ["typ:ziel"]. Kein Text davor/danach. Wenn nichts: []. Keine Objekte!
openrouter: |
TASK: Filtere relevante Kanten aus dem Pool.
ERLAUBTE TYPEN: {valid_types}
@@ -199,8 +290,10 @@ edge_allocation_template:
REGEL: Kein Text, keine Analyse, keine Kommentare. Wenn nichts passt, gib [] zurück.
OUTPUT:
default: "[]"
# ---------------------------------------------------------
# 7. SMART EDGE ALLOCATION: Extraktion (Intent: INGEST)
# 8. SMART EDGE ALLOCATION: Extraktion (Ingest)
# ---------------------------------------------------------
edge_extraction:
ollama: |
@@ -224,11 +317,13 @@ edge_extraction:
"""
DEIN OUTPUT (JSON):
gemini: |
Analysiere '{note_id}'. Extrahiere semantische Beziehungen.
ERLAUBTE TYPEN: {valid_types}
TEXT: {text}
OUTPUT: STRIKT JSON-Array von Objekten: [[{{"to\":\"Ziel\",\"kind\":\"typ\"}}]]. Kein Text davor/danach. Wenn nichts: [].
openrouter: |
TASK: Extrahiere semantische Relationen für '{note_id}'.
ERLAUBTE TYPEN: {valid_types}
@@ -239,10 +334,20 @@ edge_extraction:
Wenn keine Relationen existieren, antworte NUR mit: []
OUTPUT:
default: "[]"
# ---------------------------------------------------------
# 8. WP-15b: EDGE VALIDATION (Intent: VALIDATE)
# 9. INGESTION: EDGE VALIDATION (Ingest/Validate)
# ---------------------------------------------------------
edge_validation:
# --- Modell-spezifisch (WP-25b Optimierung) ---
"mistralai/mistral-7b-instruct:free": |
Verify relation '{edge_kind}' for graph integrity.
Chunk: "{chunk_text}"
Target: "{target_title}" ({target_summary})
Respond ONLY with 'YES' or 'NO'.
# --- EXAKTE Provider-Fallbacks aus v3.1.2 ---
gemini: |
Bewerte die semantische Validität dieser Verbindung im Wissensgraph.
@@ -257,6 +362,7 @@ edge_validation:
FRAGE: Bestätigt der Kontext der Quelle die Beziehung '{edge_kind}' zum Ziel?
REGEL: Antworte NUR mit 'YES' oder 'NO'. Keine Erklärungen oder Smalltalk.
openrouter: |
Verify semantic relation for graph construction.
Source Context: {chunk_text}
@@ -265,9 +371,83 @@ edge_validation:
Proposed Relation: {edge_kind}
Instruction: Does the source context support this relation to the target?
Result: Respond ONLY with 'YES' or 'NO'.
ollama: |
Bewerte die semantische Korrektheit dieser Verbindung.
QUELLE: {chunk_text}
ZIEL: {target_title} ({target_summary})
BEZIEHUNG: {edge_kind}
Ist diese Verbindung valide? Antworte NUR mit YES oder NO.
Ist diese Verbindung valide? Antworte NUR mit YES oder NO.
default: "YES"
# ---------------------------------------------------------
# 10. WP-25: INTENT ROUTING (Intent: CLASSIFY)
# ---------------------------------------------------------
intent_router_v1:
# --- Modell-spezifisch (WP-25b Optimierung) ---
"mistralai/mistral-7b-instruct:free": |
Classify query "{query}" into exactly one of these categories:
FACT_WHEN, FACT_WHAT, DECISION, EMPATHY, CODING, INTERVIEW.
Respond with the category name only.
# --- EXAKTE Provider-Fallbacks aus v3.1.2 ---
ollama: |
Analysiere die Nutzeranfrage und wähle die passende Strategie.
Antworte NUR mit dem Namen der Strategie.
STRATEGIEN:
- FACT_WHEN: Nur für explizite Fragen nach einem exakten Datum, Uhrzeit oder dem "Wann" eines Ereignisses.
- FACT_WHAT: Fragen nach Inhalten, Listen von Objekten/Projekten, Definitionen oder "Was/Welche" Anfragen (auch bei Zeiträumen).
- DECISION: Rat, Meinung, "Soll ich?", Abwägung gegen Werte.
- EMPATHY: Emotionen, Reflexion, Befindlichkeit.
- CODING: Programmierung, Skripte, technische Syntax.
- INTERVIEW: Dokumentation neuer Informationen, Notizen anlegen.
NACHRICHT: "{query}"
STRATEGIE:
gemini: |
Classify intent:
- FACT_WHEN: Exact dates/times only.
- FACT_WHAT: Content, lists of entities (projects, etc.), definitions, "What/Which" queries.
- DECISION: Strategic advice/values.
- EMPATHY: Emotions.
- CODING: Tech/Code.
- INTERVIEW: Data entry.
Query: "{query}"
Result (One word only):
openrouter: |
Select strategy for Mindnet:
FACT_WHEN (timing/dates), FACT_WHAT (entities/lists/what/which), DECISION, EMPATHY, CODING, INTERVIEW.
Query: "{query}"
Response:
default: "FACT_WHAT"
# ---------------------------------------------------------
# 11. WP-25b: FALLBACK SYNTHESIS (Error Recovery)
# ---------------------------------------------------------
fallback_synthesis:
ollama: |
Beantworte die folgende Frage basierend auf dem bereitgestellten Kontext.
FRAGE:
{query}
KONTEXT:
{context}
ANWEISUNG:
Nutze den Kontext, um eine präzise Antwort zu geben. Falls der Kontext unvollständig ist, weise darauf hin.
gemini: |
Frage: {query}
Kontext: {context}
Antworte basierend auf dem Kontext.
openrouter: |
Answer the question "{query}" using the provided context: {context}
default: "Answer: {query}\n\nContext: {context}"
+49 -4
View File
@@ -18,9 +18,12 @@ Das Repository ist in **logische Domänen** unterteilt.
*Zielgruppe: Alle*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `README.md` | **Einstiegspunkt.** Übersicht über die Dokumentationsstruktur, Schnellzugriff nach Rollen und Navigation. |
| `00_quickstart.md` | **Schnellstart.** Installation und erste Schritte in 15 Minuten. Ideal für neue Benutzer. |
| `00_vision_and_strategy.md` | **Strategie.** Warum bauen wir das? Prinzipien (Privacy, Local-First), High-Level Architektur. |
| `00_glossary.md` | **Definitionen.** Was bedeutet "Smart Edge", "Traffic Control", "Chunk"? Verhindert Begriffsverwirrung. |
| `00_documentation_map.md` | **Dieser Index.** Navigationshilfe. |
| `00_quality_checklist.md` | **Qualitätsprüfung.** Systematische Checkliste zur Vollständigkeitsprüfung für alle Rollen. |
### 📂 01_User_Manual (Anwendung)
*Zielgruppe: Mindmaster, Autoren, Power-User*
@@ -28,7 +31,8 @@ Das Repository ist in **logische Domänen** unterteilt.
| :--- | :--- |
| `01_chat_usage_guide.md` | **Bedienung.** Wie steuere ich die Personas (Berater, Spiegel)? Wie nutze ich das Feedback? |
| `01_knowledge_design.md` | **Content-Regeln.** Die "Bibel" für den Vault. Erklärt Note-Typen, Matrix-Logik und Markdown-Syntax. |
| `01-authoring-guidelines` | **Content strukturieren-.** primäres Werkzeug, um Wissen so zu strukturieren, so dass Mindnet die Persönlichkeit spiegelt, empathisch reagiert und strategisch berät |
| `01_authoring_guidelines.md` | **Content strukturieren.** Primäres Werkzeug, um Wissen so zu strukturieren, dass Mindnet die Persönlichkeit spiegelt, empathisch reagiert und strategisch berät. |
| `01_obsidian_integration_guide.md` | **Obsidian Setup.** Technische Anleitung für die Integration von Mindnet mit Obsidian (Templater, Skripte, Workflows). |
### 📂 02_Concepts (Fachliche Logik)
*Zielgruppe: Architekten, Product Owner*
@@ -36,6 +40,7 @@ Das Repository ist in **logische Domänen** unterteilt.
| :--- | :--- |
| `02_concept_graph_logic.md` | **Graph-Theorie.** Abstrakte Erklärung von Knoten, Kanten, Provenance und Idempotenz. |
| `02_concept_ai_personality.md`| **KI-Verhalten.** Konzepte hinter dem Hybrid Router, Empathie-Modell und "Teach-the-AI". |
| `02_concept_architecture_patterns.md` | **Architektur-Patterns.** Design-Entscheidungen, modulare Struktur (WP-14), Resilienz-Patterns und Erweiterbarkeit. |
### 📂 03_Technical_Reference (Technik & Code)
*Zielgruppe: Entwickler, DevOps. (Enthält JSON/YAML Beispiele)*
@@ -46,13 +51,16 @@ Das Repository ist in **logische Domänen** unterteilt.
| `03_tech_retrieval_scoring.md` | **Suche.** Die mathematischen Formeln für Scoring, Hybrid Search und Explanation Layer. |
| `03_tech_chat_backend.md` | **API & LLM.** Implementation des Routers, Traffic Control (Semaphore) und Feedback-Traceability. |
| `03_tech_frontend.md` | **UI & Graph.** Architektur des Streamlit-Frontends, State-Management, Cytoscape-Integration und Editor-Logik. |
| `03_tech_configuration.md` | **Config.** Referenztabellen für `.env`, `types.yaml` und `retriever.yaml`. |
| `03_tech_configuration.md` | **Config.** Referenztabellen für `.env`, `types.yaml`, `decision_engine.yaml`, `llm_profiles.yaml`, `prompts.yaml`. **Neu:** Verbindungen zwischen Config-Dateien, Praxisbeispiel und Mermaid-Grafik. |
| `03_tech_api_reference.md` | **API-Referenz.** Vollständige Dokumentation aller Endpunkte (`/query`, `/chat`, `/ingest`, `/graph`, etc.). |
### 📂 04_Operations (Betrieb)
*Zielgruppe: Administratoren*
| Datei | Inhalt & Zweck |
| :--- | :--- |
| `04_admin_operations.md` | **Runbook.** Installation, Docker-Setup, Backup/Restore, Troubleshooting Guide. |
| `04_server_operation_manual.md` | **Server-Betrieb.** Detaillierte Dokumentation für den Betrieb auf llm-node (Systemd, Borgmatic, Disaster Recovery). |
| `04_deployment_guide.md` | **Deployment.** CI/CD-Pipelines, Rollout-Strategien, Versionierung, Rollback und Pre/Post-Deployment-Checklisten. |
### 📂 05_Development (Code)
*Zielgruppe: Entwickler*
@@ -60,6 +68,7 @@ Das Repository ist in **logische Domänen** unterteilt.
| :--- | :--- |
| `05_developer_guide.md` | **Workflow.** Hardware-Setup (Win/Pi/Beelink), Git-Flow, Test-Befehle, Modul-Interna. |
| `05_genai_best_practices.md` | **AI Workflow.** Prompt-Library, Templates und Best Practices für die Entwicklung mit LLMs. |
| `05_testing_guide.md` | **Testing.** Umfassender Test-Guide: Strategien, Frameworks, Test-Daten, Best Practices. |
### 📂 06_Roadmap & 99_Archive
*Zielgruppe: Projektleitung*
@@ -82,7 +91,9 @@ Nutze diese Matrix, wenn du ein Workpackage bearbeitest, um die Dokumentation ko
| **Retrieval / Scoring** | `03_tech_retrieval_scoring.md` (Formeln anpassen) |
| **Frontend / Visualisierung** | 1. `03_tech_frontend.md` (Technische Details)<br>2. `01_chat_usage_guide.md` (Bedienung) |
| **Chat-Logik / Prompts**| 1. `02_concept_ai_personality.md` (Konzept)<br>2. `03_tech_chat_backend.md` (Tech)<br>3. `01_chat_usage_guide.md` (User-Sicht) |
| **Deployment / Server** | `04_admin_operations.md` |
| **Architektur / Design-Patterns** | 1. `02_concept_architecture_patterns.md` (Patterns & Entscheidungen)<br>2. `02_concept_graph_logic.md` (Graph-Theorie)<br>3. `05_developer_guide.md` (Modulare Struktur) |
| **Deployment / Server** | 1. `04_deployment_guide.md` (CI/CD, Rollout)<br>2. `04_admin_operations.md` (Installation, Wartung)<br>3. `04_server_operation_manual.md` (Server-Betrieb) |
| **Testing / QA** | 1. `05_testing_guide.md` (Test-Strategien & Frameworks)<br>2. `05_developer_guide.md` (Test-Befehle) |
| **Neuen Features (Allg.)**| `06_active_roadmap.md` (Status Update) |
---
@@ -110,4 +121,38 @@ Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten
audience: developer
context: "Beschreibung der Scoring-Formel."
---
```
```
---
## 5. Schnellzugriff & Empfehlungen
### Für neue Benutzer
1. Starte mit **[Schnellstart](00_quickstart.md)** für die Installation
2. Lese **[Vision & Strategie](00_vision_and_strategy.md)** für das große Bild
3. Nutze **[Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md)** für die ersten Schritte
### Für Entwickler
1. **[Developer Guide](../05_Development/05_developer_guide.md)** - Umfassender technischer Guide
2. **[Technical References](../03_Technical_References/)** - Detaillierte API- und Architektur-Dokumentation
3. **[GenAI Best Practices](../05_Development/05_genai_best_practices.md)** - Workflow mit LLMs
### Für Administratoren
1. **[Admin Operations](../04_Operations/04_admin_operations.md)** - Installation und Wartung
2. **[Server Operations Manual](../04_Operations/04_server_operation_manual.md)** - Server-Betrieb und Disaster Recovery
3. **[Troubleshooting Guide](../04_Operations/04_admin_operations.md#33-troubleshooting-guide)** - Häufige Probleme und Lösungen
### Für Autoren
1. **[Knowledge Design](../01_User_Manual/01_knowledge_design.md)** - Content-Regeln und Best Practices
2. **[Authoring Guidelines](../01_User_Manual/01_authoring_guidelines.md)** - Strukturierung für den Digitalen Zwilling
3. **[Obsidian Integration](../01_User_Manual/01_obsidian_integration_guide.md)** - Workflow-Optimierung
---
## 6. Dokumentations-Status
**Aktuelle Version:** 3.1.1
**Letzte Aktualisierung:** 2026-01-02
**Status:** ✅ Vollständig und aktiv gepflegt
**Hinweis:** Diese Dokumentation wird kontinuierlich aktualisiert. Bei Fragen oder Verbesserungsvorschlägen bitte im Repository melden.
+22 -5
View File
@@ -2,8 +2,8 @@
doc_type: glossary
audience: all
status: active
version: 2.8.1
context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-14 Modularisierung, WP-15b Two-Pass Ingestion und Mistral-safe Parsing."
version: 3.1.1
context: "Zentrales Glossar für Mindnet v3.1.1. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-14 Modularisierung, WP-15b Two-Pass Ingestion, WP-15c Multigraph-Support, WP-25 Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE), WP-25b Lazy-Prompt-Orchestration und Mistral-safe Parsing."
---
# Mindnet Glossar
@@ -14,7 +14,7 @@ context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-C
* **Note:** Repräsentiert eine Markdown-Datei. Die fachliche Haupteinheit. Verfügt über einen **Status** (stable, draft, system), der das Scoring beeinflusst.
* **Chunk:** Ein Textabschnitt einer Note. Die technische Sucheinheit (Vektor).
* **Edge:** Eine gerichtete Verbindung zwischen zwei Knoten. Wird in WP-22 durch die Registry validiert.
* **Edge:** Eine gerichtete Verbindung zwischen zwei Knoten. Wird in WP-22 durch die Registry validiert. Seit v2.9.1 unterstützt Edges **Section-basierte Links** (`target_section`), sodass mehrere Kanten zwischen denselben Knoten existieren können, wenn sie auf verschiedene Abschnitte zeigen.
* **Vault:** Der lokale Ordner mit den Markdown-Dateien (Source of Truth).
* **Frontmatter:** Der YAML-Header am Anfang einer Notiz (enthält `id`, `type`, `title`, `status`).
@@ -23,7 +23,11 @@ context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-C
* **Edge Registry:** Der zentrale Dienst (SSOT), der Kanten-Typen validiert und Aliase in kanonische Typen auflöst. Nutzt `01_edge_vocabulary.md` als Basis.
* **LLM Service:** Der Hybrid-Client (v3.3.6), der Anfragen zwischen OpenRouter, Google Gemini und lokalem Ollama routet. Verwaltet Cloud-Timeouts und Quoten-Management. Nutzt zur Text-Bereinigung nun die neutrale `registry.py`, um Circular Imports zu vermeiden.
* **Retriever:** Besteht in v2.7+ aus der Orchestrierung (`retriever.py`) und der mathematischen Scoring-Engine (`retriever_scoring.py`). Seit WP-14 im Paket `app.core.retrieval` gekapselt.
* **Decision Engine:** Teil des Routers, der Intents erkennt und entsprechende **Boost-Faktoren** für das Retrieval injiziert.
* **Decision Engine (WP-25):** Der zentrale **Agentic Orchestrator**, der Intents erkennt, parallele Wissens-Streams orchestriert und die Ergebnisse synthetisiert. Implementiert Multi-Stream Retrieval und Intent-basiertes Routing.
* **Agentic Multi-Stream RAG (WP-25):** Architektur-Paradigma, bei dem Nutzeranfragen in parallele, spezialisierte Wissens-Streams aufgeteilt werden (Values, Facts, Biography, Risk, Tech), die gleichzeitig abgefragt und zu einer kontextreichen Antwort synthetisiert werden.
* **Stream-Tracing (WP-25):** Kennzeichnung jedes Treffers mit seinem Ursprungs-Stream (`stream_origin`), um Feedback-Optimierung pro Wissensbereich zu ermöglichen.
* **Intent-basiertes Routing (WP-25):** Hybrid-Modus zur Intent-Erkennung mit Keyword Fast-Path (sofortige Erkennung von Triggern) und LLM Slow-Path (semantische Analyse für unklare Anfragen).
* **Wissens-Synthese (WP-25):** Template-basierte Zusammenführung der Ergebnisse aus parallelen Streams mit expliziten Stream-Variablen (z.B. `{values_stream}`, `{risk_stream}`), um dem LLM eine differenzierte Abwägung zu ermöglichen.
* **Traffic Control:** Verwaltet Prioritäten und drosselt Hintergrund-Tasks (z.B. Smart Edges) mittels Semaphoren und Timeouts (45s) zur Vermeidung von System-Hangs.
* **Unknown Edges Log:** Die Datei `unknown_edges.jsonl`, in der das System Kanten-Typen protokolliert, die nicht im Dictionary gefunden wurden.
* **Database Package (WP-14):** Zentralisiertes Infrastruktur-Paket (`app.core.database`), das den Qdrant-Client (`qdrant.py`) und das Point-Mapping (`qdrant_points.py`) verwaltet.
@@ -47,4 +51,17 @@ context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-C
* **Two-Pass Workflow (WP-15b):** Optimiertes Ingestion-Verfahren:
* **Pass 1 (Pre-Scan):** Schnelles Scannen aller Dateien zur Befüllung des LocalBatchCache.
* **Pass 2 (Semantic Processing):** Tiefenverarbeitung (Chunking, Embedding, Validierung) nur für geänderte Dateien.
* **Circular Import Registry (WP-14):** Entkopplung von Kern-Logik (wie Textbereinigung) in eine neutrale `registry.py`, um Abhängigkeitsschleifen zwischen Diensten und Ingestion-Utilities zu verhindern.
* **Circular Import Registry (WP-14):** Entkopplung von Kern-Logik (wie Textbereinigung) in eine neutrale `registry.py`, um Abhängigkeitsschleifen zwischen Diensten und Ingestion-Utilities zu verhindern.
* **Deep-Link / Section-basierter Link:** Ein Link wie `[[Note#Section]]`, der auf einen spezifischen Abschnitt innerhalb einer Note verweist. Seit v2.9.1 wird dieser in `target_id="Note"` und `target_section="Section"` aufgeteilt, um "Phantom-Knoten" zu vermeiden und Multigraph-Support zu ermöglichen.
* **Atomic Section Logic (v3.9.9):** Chunking-Verfahren, das Sektions-Überschriften und deren Inhalte atomar in Chunks hält (Pack-and-Carry-Over). Verhindert, dass Überschriften über Chunk-Grenzen hinweg getrennt werden.
* **Registry-First Profiling (v2.13.12):** Hierarchische Auflösung des Chunking-Profils: Frontmatter > types.yaml Typ-Config > Global Defaults. Stellt sicher, dass Note-Typen automatisch das korrekte Profil erhalten.
* **Mixture of Experts (MoE) - WP-25a:** Profilbasierte Experten-Architektur, bei der jede Systemaufgabe (Synthese, Ingestion-Validierung, Routing, Kompression) einem dedizierten Profil zugewiesen wird, das Modell, Provider und Parameter unabhängig von der globalen Konfiguration definiert.
* **LLM-Profil:** Zentrale Definition in `llm_profiles.yaml`, die Provider, Modell, Temperature und Fallback-Profil für eine spezifische Aufgabe festlegt (z.B. `synthesis_pro`, `tech_expert`, `ingest_validator`).
* **Fallback-Kaskade (WP-25a):** Rekursive Fallback-Logik, bei der bei Fehlern automatisch auf das `fallback_profile` umgeschaltet wird, bis der terminale Endpunkt (`identity_safe`) erreicht wird. Schutz gegen Zirkel-Referenzen via `visited_profiles`-Tracking.
* **Pre-Synthesis Kompression (WP-25a):** Asynchrone Verdichtung überlanger Wissens-Streams vor der Synthese, um Token-Verbrauch zu reduzieren und die Synthese zu beschleunigen. Nutzt `compression_profile` (z.B. `compression_fast`).
* **Profilgesteuerte Validierung (WP-25a):** Semantische Kanten-Validierung in der Ingestion erfolgt zwingend über das MoE-Profil `ingest_validator` (Temperature 0.0 für Determinismus), unabhängig von der globalen Provider-Konfiguration.
* **Lazy-Prompt-Orchestration (WP-25b):** Hierarchisches Prompt-Resolution-System, das Prompts erst im Moment des Modellaustauschs lädt, basierend auf dem exakt aktiven Modell. Ermöglicht modell-spezifisches Tuning und maximale Resilienz bei Modell-Fallbacks.
* **Hierarchische Prompt-Resolution (WP-25b):** Dreistufige Auflösungs-Logik: Level 1 (Modell-ID) → Level 2 (Provider) → Level 3 (Default). Gewährleistet, dass jedes Modell das optimale Template erhält.
* **PROMPT-TRACE (WP-25b):** Logging-Mechanismus, der die genutzte Prompt-Auflösungs-Ebene protokolliert (`🎯 Level 1`, `📡 Level 2`, `⚓ Level 3`). Bietet vollständige Transparenz über die genutzten Instruktionen.
* **Ultra-robustes Intent-Parsing (WP-25b):** Regex-basierter Intent-Parser in der DecisionEngine, der Modell-Artefakte wie `[/S]`, `</s>` oder Newlines zuverlässig bereinigt, um präzises Strategie-Routing zu gewährleisten.
* **Differenzierte Ingestion-Validierung (WP-25b):** Unterscheidung zwischen transienten Fehlern (Netzwerk, Timeout) und permanenten Fehlern (Config, Validation). Transiente Fehler erlauben die Kante (Datenverlust vermeiden), permanente Fehler lehnen sie ab (Graph-Qualität schützen).
+166
View File
@@ -0,0 +1,166 @@
---
doc_type: quality_assurance
audience: all
status: active
version: 2.9.1
context: "Qualitätsprüfung der Dokumentation für alle Rollen: Vollständigkeit, Korrektheit und Anwendbarkeit."
---
# Dokumentations-Qualitätsprüfung
Diese Checkliste dient zur systematischen Prüfung, ob die Dokumentation alle Fragen jeder Rolle vollständig beantwortet.
## ✅ Entwickler
### Setup & Installation
- [x] **Lokales Setup:** [Developer Guide](../05_Development/05_developer_guide.md#6-lokales-setup-development)
- [x] **Schnellstart:** [Quickstart](00_quickstart.md)
- [x] **Hardware-Anforderungen:** [Admin Operations](../04_Operations/04_admin_operations.md#11-voraussetzungen)
### Architektur & Code
- [x] **Modulare Struktur:** [Developer Guide - Architektur](../05_Development/05_developer_guide.md#4-projektstruktur--modul-referenz-deep-dive)
- [x] **Design-Patterns:** [Architektur-Patterns](../02_concepts/02_concept_architecture_patterns.md)
- [x] **API-Referenz:** [API Reference](../03_Technical_References/03_tech_api_reference.md)
- [x] **Datenmodell:** [Data Model](../03_Technical_References/03_tech_data_model.md)
### Entwicklung & Erweiterung
- [x] **Workflow:** [Developer Guide - Workflow](../05_Development/05_developer_guide.md#7-der-entwicklungs-zyklus-workflow)
- [x] **Erweiterungs-Guide:** [Teach-the-AI](../05_Development/05_developer_guide.md#8-erweiterungs-guide-teach-the-ai)
- [x] **GenAI Best Practices:** [GenAI Best Practices](../05_Development/05_genai_best_practices.md)
### Testing
- [x] **Test-Strategien:** [Testing Guide](../05_Development/05_testing_guide.md)
- [x] **Test-Frameworks:** [Testing Guide - Frameworks](../05_Development/05_testing_guide.md#3-test-frameworks--tools)
- [x] **Test-Daten:** [Testing Guide - Test-Daten](../05_Development/05_testing_guide.md#2-test-daten--vaults)
### Debugging & Troubleshooting
- [x] **Troubleshooting:** [Developer Guide - Troubleshooting](../05_Development/05_developer_guide.md#10-troubleshooting--one-liners)
- [x] **Debug-Tools:** [Testing Guide - Debugging](../05_Development/05_testing_guide.md#7-debugging--diagnose)
---
## ✅ Administratoren
### Installation & Setup
- [x] **Installation:** [Admin Operations](../04_Operations/04_admin_operations.md#1-installation--setup)
- [x] **Docker Setup:** [Admin Operations - Qdrant](../04_Operations/04_admin_operations.md#12-qdrant-docker)
- [x] **Systemd Services:** [Admin Operations - Deployment](../04_Operations/04_admin_operations.md#2-deployment-systemd-services)
### Betrieb & Wartung
- [x] **Monitoring:** [Admin Operations - Wartung](../04_Operations/04_admin_operations.md#3-wartung--monitoring)
- [x] **Backup & Restore:** [Admin Operations - Backup](../04_Operations/04_admin_operations.md#4-backup--restore)
- [x] **Troubleshooting:** [Admin Operations - Troubleshooting](../04_Operations/04_admin_operations.md#33-troubleshooting-guide)
### Server-Betrieb
- [x] **Server-Konfiguration:** [Server Operations Manual](../04_Operations/04_server_operation_manual.md)
- [x] **Disaster Recovery:** [Server Operations - DR](../04_Operations/04_server_operation_manual.md#5-disaster-recovery-wiederherstellung-two-stage-dr)
- [x] **Backup-Strategie:** [Server Operations - Backup](../04_Operations/04_server_operation_manual.md#4-backup-strategie-borgmatic)
### Konfiguration
- [x] **ENV-Variablen:** [Configuration Reference](../03_Technical_References/03_tech_configuration.md#1-environment-variablen-env)
- [x] **YAML-Configs:** [Configuration Reference - YAML](../03_Technical_References/03_tech_configuration.md#2-typ-registry-typesyaml)
---
## ✅ Anwender
### Erste Schritte
- [x] **Schnellstart:** [Quickstart](00_quickstart.md)
- [x] **Was ist Mindnet:** [Vision & Strategie](00_vision_and_strategy.md)
- [x] **Grundlagen:** [Glossar](00_glossary.md)
### Nutzung
- [x] **Chat-Bedienung:** [Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md)
- [x] **Graph Explorer:** [Chat Usage Guide - Graph](../01_User_Manual/01_chat_usage_guide.md#22-modus--graph-explorer-cytoscape)
- [x] **Editor:** [Chat Usage Guide - Editor](../01_User_Manual/01_chat_usage_guide.md#23-modus--manueller-editor)
### Content-Erstellung
- [x] **Knowledge Design:** [Knowledge Design Manual](../01_User_Manual/01_knowledge_design.md)
- [x] **Authoring Guidelines:** [Authoring Guidelines](../01_User_Manual/01_authoring_guidelines.md)
- [x] **Obsidian-Integration:** [Obsidian Integration](../01_User_Manual/01_obsidian_integration_guide.md)
### Häufige Fragen
- [x] **Wie strukturiere ich Notizen?** → [Knowledge Design](../01_User_Manual/01_knowledge_design.md)
- [x] **Welche Note-Typen gibt es?** → [Knowledge Design - Typ-Referenz](../01_User_Manual/01_knowledge_design.md#31-typ-referenz--stream-logik)
- [x] **Wie verknüpfe ich Notizen?** → [Knowledge Design - Edges](../01_User_Manual/01_knowledge_design.md#4-edges--verlinkung)
- [x] **Wie nutze ich den Chat?** → [Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md)
---
## ✅ Tester
### Test-Strategien
- [x] **Test-Pyramide:** [Testing Guide - Strategien](../05_Development/05_testing_guide.md#1-test-strategie--ebenen)
- [x] **Unit Tests:** [Testing Guide - Unit Tests](../05_Development/05_testing_guide.md#11-unit-tests-pytest)
- [x] **Integration Tests:** [Testing Guide - Integration](../05_Development/05_testing_guide.md#12-integration-tests)
- [x] **E2E Tests:** [Testing Guide - E2E](../05_Development/05_testing_guide.md#13-e2e--smoke-tests)
### Test-Frameworks
- [x] **Pytest:** [Testing Guide - Frameworks](../05_Development/05_testing_guide.md#31-pytest-unit-tests)
- [x] **Unittest:** [Testing Guide - Unittest](../05_Development/05_testing_guide.md#32-unittest-e2e-tests)
- [x] **Shell-Skripte:** [Testing Guide - Shell](../05_Development/05_testing_guide.md#33-shell-skripte-e2e-roundtrip)
### Test-Daten & Tools
- [x] **Test-Vault erstellen:** [Testing Guide - Test-Daten](../05_Development/05_testing_guide.md#21-test-vault-erstellen)
- [x] **Test-Skripte:** [Developer Guide - Scripts](../05_Development/05_developer_guide.md#44-scripts--tooling-die-admin-toolbox)
- [x] **Test-Checkliste:** [Testing Guide - Checkliste](../05_Development/05_testing_guide.md#8-test-checkliste-für-pull-requests)
---
## ✅ Deployment
### Deployment-Prozesse
- [x] **Deployment-Guide:** [Deployment Guide](../04_Operations/04_deployment_guide.md)
- [x] **CI/CD Pipeline:** [Deployment Guide - CI/CD](../04_Operations/04_deployment_guide.md#9-cicd-pipeline-details)
- [x] **Rollout-Strategien:** [Deployment Guide - Rollout](../04_Operations/04_deployment_guide.md#4-rollout-strategien)
### Versionierung & Releases
- [x] **Version-Schema:** [Deployment Guide - Versionierung](../04_Operations/04_deployment_guide.md#51-version-schema)
- [x] **Release-Prozess:** [Deployment Guide - Release](../04_Operations/04_deployment_guide.md#52-release-prozess)
### Rollback & Recovery
- [x] **Rollback-Strategien:** [Deployment Guide - Rollback](../04_Operations/04_deployment_guide.md#6-rollback-strategien)
- [x] **Disaster Recovery:** [Server Operations - DR](../04_Operations/04_server_operation_manual.md#5-disaster-recovery-wiederherstellung-two-stage-dr)
### Pre/Post-Deployment
- [x] **Pre-Deployment Checkliste:** [Deployment Guide - Checkliste](../04_Operations/04_deployment_guide.md#7-pre-deployment-checkliste)
- [x] **Post-Deployment Validierung:** [Deployment Guide - Validierung](../04_Operations/04_deployment_guide.md#8-post-deployment-validierung)
---
## 📊 Zusammenfassung
### Vollständigkeit nach Rolle
| Rolle | Abgedeckte Themen | Status |
| :--- | :--- | :--- |
| **Entwickler** | Setup, Architektur, Code, Testing, Debugging | ✅ Vollständig |
| **Administratoren** | Installation, Betrieb, Wartung, Backup, DR | ✅ Vollständig |
| **Anwender** | Nutzung, Content-Erstellung, Workflows | ✅ Vollständig |
| **Tester** | Test-Strategien, Frameworks, Tools | ✅ Vollständig |
| **Deployment** | CI/CD, Rollout, Versionierung, Rollback | ✅ Vollständig |
### Neue Dokumente
1. ✅ `05_testing_guide.md` - Umfassender Test-Guide
2. ✅ `04_deployment_guide.md` - Vollständiger Deployment-Guide
3. ✅ `02_concept_architecture_patterns.md` - Architektur-Patterns
4. ✅ `03_tech_api_reference.md` - API-Referenz
5. ✅ `00_quickstart.md` - Schnellstart-Anleitung
6. ✅ `README.md` - Dokumentations-Einstiegspunkt
### Aktualisierte Dokumente
1. ✅ `00_documentation_map.md` - Alle neuen Dokumente aufgenommen
2. ✅ `04_admin_operations.md` - Troubleshooting erweitert
3. ✅ `05_developer_guide.md` - Modulare Struktur ergänzt
4. ✅ `03_tech_ingestion_pipeline.md` - Background Tasks dokumentiert
5. ✅ `03_tech_configuration.md` - Fehlende ENV-Variablen ergänzt
6. ✅ `00_vision_and_strategy.md` - Design-Entscheidungen ergänzt
---
**Status:** ✅ Alle Rollen vollständig abgedeckt
**Letzte Prüfung:** 2025-01-XX
**Version:** 2.9.1
+156
View File
@@ -0,0 +1,156 @@
---
doc_type: quickstart_guide
audience: user, developer, admin
status: active
version: 2.9.1
context: "Schnellstart-Anleitung für neue Benutzer von Mindnet"
---
# Mindnet Schnellstart
Diese Anleitung hilft dir, in 15 Minuten mit Mindnet loszulegen.
## 🎯 Was ist Mindnet?
Mindnet ist ein **persönliches KI-Gedächtnis**, das:
- Dein Wissen in Markdown-Notizen speichert
- Semantisch verknüpft (Wissensgraph)
- Als intelligenter Dialogpartner agiert (RAG-Chat)
- **Lokal und privat** läuft (Privacy First)
## 📋 Voraussetzungen
- **Python 3.10+** installiert
- **Docker** installiert (für Qdrant)
- **Ollama** installiert (für lokale LLMs)
- Optional: **Obsidian** (für komfortables Schreiben)
## ⚡ Installation (5 Minuten)
### Schritt 1: Repository klonen
```bash
git clone <repository-url> mindnet
cd mindnet
```
### Schritt 2: Virtuelle Umgebung erstellen
```bash
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
```
### Schritt 3: Abhängigkeiten installieren
```bash
pip install -r requirements.txt
```
### Schritt 4: Qdrant starten (Docker)
```bash
docker compose up -d qdrant
```
### Schritt 5: Ollama-Modelle laden
```bash
ollama pull phi3:mini
ollama pull nomic-embed-text
```
### Schritt 6: Konfiguration anpassen
Erstelle eine `.env`-Datei im Projektroot:
```ini
QDRANT_URL=http://localhost:6333
MINDNET_OLLAMA_URL=http://localhost:11434
MINDNET_LLM_MODEL=phi3:mini
MINDNET_EMBEDDING_MODEL=nomic-embed-text
COLLECTION_PREFIX=mindnet
MINDNET_VAULT_ROOT=./vault
```
## 🚀 Erste Schritte (5 Minuten)
### Schritt 1: Backend starten
```bash
uvicorn app.main:app --reload --port 8001
```
### Schritt 2: Frontend starten (neues Terminal)
```bash
streamlit run app/frontend/ui.py --server.port 8501
```
### Schritt 3: Browser öffnen
Öffne `http://localhost:8501` im Browser.
### Schritt 4: Erste Notiz importieren
Erstelle eine Test-Notiz im `vault/` Ordner:
```markdown
---
id: 20250101-test
title: Meine erste Notiz
type: concept
status: active
---
# Meine erste Notiz
Dies ist eine Test-Notiz für Mindnet.
[[rel:related_to Mindnet]]
```
Dann importiere sie:
```bash
python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply
```
### Schritt 5: Erste Chat-Anfrage
Im Browser-Chat eingeben:
```
Was ist Mindnet?
```
## 📚 Nächste Schritte
Nach dem Schnellstart empfehle ich:
1. **[Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md)** - Lerne die Chat-Funktionen kennen
2. **[Knowledge Design](../01_User_Manual/01_knowledge_design.md)** - Verstehe, wie du Notizen strukturierst
3. **[Authoring Guidelines](../01_User_Manual/01_authoring_guidelines.md)** - Lerne Best Practices für das Schreiben
## 🆘 Hilfe & Troubleshooting
**Problem:** Qdrant startet nicht
- **Lösung:** Prüfe, ob Docker läuft: `docker ps`
**Problem:** Ollama-Modell nicht gefunden
- **Lösung:** Prüfe mit `ollama list`, ob die Modelle geladen sind
**Problem:** Import schlägt fehl
- **Lösung:** Prüfe die Logs und stelle sicher, dass Qdrant läuft
Für detaillierte Troubleshooting-Informationen siehe [Admin Operations](../04_Operations/04_admin_operations.md#33-troubleshooting-guide).
## 🔗 Weitere Ressourcen
- **[Dokumentationskarte](00_documentation_map.md)** - Übersicht aller Dokumente
- **[Glossar](00_glossary.md)** - Wichtige Begriffe erklärt
- **[Vision & Strategie](00_vision_and_strategy.md)** - Die Philosophie hinter Mindnet
---
**Viel Erfolg mit Mindnet!** 🚀
+39 -1
View File
@@ -64,4 +64,42 @@ Die folgenden Prinzipien steuern jede technische Entscheidung:
Jeder Importlauf und jede Retriever-Anfrage ist logbar.
10. **Local First & Privacy:**
Nutzung lokaler LLMs (Ollama) für Inference. Keine Daten verlassen den Server.
Nutzung lokaler LLMs (Ollama) für Inference. Keine Daten verlassen den Server.
11. **Modulare Architektur (WP-14):**
Core-Logik ist in spezialisierte Pakete unterteilt (`chunking/`, `database/`, `graph/`, `ingestion/`, `parser/`, `retrieval/`). Dies ermöglicht unabhängige Entwicklung, Testbarkeit und Wartbarkeit.
12. **Resilienz durch Kaskaden:**
System nutzt Provider-Kaskaden (Cloud → Rate-Limit-Handling → Lokaler Fallback) für hohe Verfügbarkeit. Deep Fallback erkennt auch kognitive Blockaden (Silent Refusals).
---
## 4. Design-Entscheidungen & Trade-offs
### 4.1 Qdrant als Vektor-DB
**Entscheidung:** Self-hosted Qdrant statt Managed Service (Pinecone/Weaviate)
**Gründe:** Privacy First, Open Source, lokale Kontrolle
**Trade-off:** Mehr Wartungsaufwand, aber vollständige Datenhoheit
### 4.2 Hybrid Retrieval
**Entscheidung:** Kombination von Vektor-Suche (Semantik) und Graph-Expansion
**Gründe:** Bessere Relevanz durch strukturelle Verbindungen
**Trade-off:** Höhere Komplexität, aber deutlich bessere Ergebnisse
### 4.3 Background Tasks statt Queue-System
**Entscheidung:** FastAPI Background Tasks statt Redis/RabbitMQ
**Gründe:** Einfacher Setup, ausreichend für Single-User
**Trade-off:** Keine Persistenz bei Server-Neustart, aber weniger Infrastruktur
### 4.4 Markdown als Source of Truth
**Entscheidung:** Markdown-Dateien sind primär, Datenbank ist Cache
**Gründe:** Versionierbarkeit, Editierbarkeit, Unabhängigkeit
**Trade-off:** Zwei Datenquellen, aber maximale Flexibilität
---
## 5. Weitere Informationen
- **Architektur-Patterns:** Siehe [Architektur-Patterns](../02_concepts/02_concept_architecture_patterns.md)
- **Graph-Logik:** Siehe [Graph-Logik](../02_concepts/02_concept_graph_logic.md)
- **KI-Persönlichkeit:** Siehe [KI-Persönlichkeit](../02_concepts/02_concept_ai_personality.md)
+128 -12
View File
@@ -3,14 +3,16 @@ doc_type: user_manual
audience: user, mindmaster
scope: chat, ui, feedback, graph
status: active
version: 2.6
context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas und des Graph Explorers."
version: 2.9.3
context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas, Multi-Stream RAG und des Graph Explorers."
---
# Chat & Graph Usage Guide
**Quellen:** `user_guide.md`
> 💡 **Tipp für Einsteiger:** Falls du noch nie mit Mindnet gearbeitet hast, starte mit dem [Schnellstart](../00_General/00_quickstart.md) und dem [Knowledge Design Manual](01_knowledge_design.md), um die Grundlagen zu verstehen.
## 1. Was Mindnet für dich tut
Mindnet ist ein **assoziatives Gedächtnis** mit Persönlichkeit. Es unterscheidet sich von einer reinen Suche dadurch, dass es **kontextsensitiv** agiert.
@@ -58,21 +60,49 @@ Ein Editor mit **"File System First"** Garantie.
---
## 3. Den Chat steuern (Intents)
## 3. Den Chat steuern (Intents & Multi-Stream RAG)
Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Der **Hybrid Router v5** unterscheidet intelligent:
Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Seit WP-25 nutzt Mindnet **Agentic Multi-Stream RAG**, das deine Anfrage in parallele Wissens-Streams aufteilt:
### 3.1 Frage-Modus (Wissen abrufen)
Ausgelöst durch `?` oder W-Wörter.
### 3.1 Intent-Erkennung (Hybrid-Router)
Der Router erkennt deine Absicht auf zwei Wegen:
**Schnelle Erkennung (Keyword Fast-Path):**
* **"Soll ich..."** → Sofortige Erkennung als `DECISION` (Berater)
* **"Wann..."** → Sofortige Erkennung als `FACT_WHEN` (Zeitpunkte)
* **"Was ist..."** → Sofortige Erkennung als `FACT_WHAT` (Wissen)
* **"Ich fühle..."** → Sofortige Erkennung als `EMPATHY` (Spiegel)
**Intelligente Analyse (LLM Slow-Path):**
* Bei unklaren Anfragen analysiert die KI semantisch deine Absicht
### 3.2 Multi-Stream Retrieval (WP-25)
Anstelle einer einzelnen Suche führt Mindnet nun **parallele Abfragen** in spezialisierten Wissens-Streams aus:
**Die Streams:**
* **Values Stream:** Deine Identität, Ethik und Prinzipien (`value`, `principle`, `belief`)
* **Facts Stream:** Operative Daten zu Projekten, Tasks und Status (`project`, `decision`, `task`)
* **Biography Stream:** Persönliche Erfahrungen und Journal-Einträge (`experience`, `journal`)
* **Risk Stream:** Hindernisse und potenzielle Gefahren (`risk`, `obstacle`)
* **Tech Stream:** Technisches Wissen, Code und Dokumentation (`concept`, `source`, `glossary`)
**Vorteil:** Jeder Stream fokussiert auf spezifische Wissensbereiche, was zu präziseren und kontextreicheren Antworten führt.
### 3.3 Frage-Modi (Strategien)
* **Entscheidung ("Soll ich?"):** Der **Berater**.
* Mindnet lädt deine Werte (`type: value`) und Ziele (`type: goal`).
* Nutzt: Values Stream, Facts Stream, Risk Stream
* Wägt Fakten gegen deine Werte ab und evaluiert Risiken
* *Beispiel:* "Soll ich Tool X nutzen?" -> "Nein, Tool X speichert Daten in den USA. Das verstößt gegen dein Prinzip 'Privacy First'."
* **Empathie ("Ich fühle..."):** Der **Spiegel**.
* Mindnet lädt deine Erfahrungen (`type: experience`).
* Nutzt: Biography Stream, Values Stream
* Greift auf deine Erfahrungen und Werte zurück
* *Beispiel:* "Ich bin frustriert." -> "Das erinnert mich an Projekt Y, da ging es uns ähnlich..."
* **Fakten ("Was ist?"):** Der **Bibliothekar**.
* Liefert präzise Definitionen.
* **Fakten ("Was ist?", "Wann..."):** Der **Bibliothekar**.
* Nutzt: Facts Stream, Tech Stream, Biography Stream
* Liefert präzise Definitionen und zeitliche Informationen
### 3.2 Befehls-Modus (Interview)
Ausgelöst durch Aussagen wie "Neues Projekt", "Ich will festhalten".
@@ -82,13 +112,17 @@ Ausgelöst durch Aussagen wie "Neues Projekt", "Ich will festhalten".
---
## 4. Ergebnisse interpretieren (Explanation Layer)
## 4. Ergebnisse interpretieren (Explanation Layer & Stream-Tracing)
Mindnet liefert eine **Begründung** ("Reasons"), warum es etwas gefunden hat.
Öffne eine Quellen-Karte, um zu sehen:
* *"Hohe textuelle Übereinstimmung."* (Semantik)
* *"Bevorzugt aufgrund des Typs 'decision'."* (Wichtigkeit)
* *"Verweist auf 'Projekt X' via 'depends_on'."* (Graph-Kontext)
* *"Quelle: Values Stream"* (Stream-Tracing - WP-25)
**Stream-Tracing (WP-25):**
Jede Quelle wird mit ihrem Ursprungs-Stream markiert (z.B. "Values Stream", "Facts Stream"). Dies hilft dir zu verstehen, aus welchem Wissensbereich die Information stammt.
---
@@ -123,4 +157,86 @@ Wenn du im **manuellen Editor** schreibst, unterstützt dich Mindnet aktiv bei d
* **Exakte Treffer:** Das System erkennt Begriffe wie "KI-Gedächtnis" als Alias für "Mindnet".
* **Semantische Treffer:** Das System findet inhaltlich verwandte Notizen.
* **Klick auf "➕ Einfügen":** Fügt den Link (z.B. `[[rel:related_to Mindnet]]`) an der Cursor-Position ein.
4. **Speichern:** Der Text wird sofort in den Vault geschrieben und indiziert.
4. **Speichern:** Der Text wird sofort in den Vault geschrieben und indiziert.
### 6.3 Weg C: Direktes Schreiben in Obsidian
Wenn du Obsidian nutzt, kannst du Notizen direkt im Vault erstellen. Nach dem Speichern in Obsidian:
1. **Automatischer Import (Cron):** Der stündliche Cron-Job importiert neue/geänderte Dateien automatisch.
2. **Manueller Import:** Oder führe manuell aus:
```bash
python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply
```
**Vorteil:** Du arbeitest in deiner gewohnten Obsidian-Umgebung, Mindnet synchronisiert im Hintergrund.
---
## 7. Häufige Anwendungsfälle (Use Cases)
### 7.1 Entscheidungshilfe suchen
**Szenario:** Du stehst vor einer schwierigen Entscheidung.
**Vorgehen:**
1. Stelle eine Frage im Chat: *"Soll ich Tool X nutzen?"*
2. Mindnet erkennt `DECISION` Intent
3. System lädt deine Werte, Prinzipien und Ziele
4. Antwort berücksichtigt deine persönlichen Kriterien
**Beispiel:** *"Soll ich Notion nutzen?"* → System prüft gegen dein Prinzip "Privacy First" und rät ab.
### 7.2 Erfahrungen dokumentieren
**Szenario:** Du willst ein prägendes Erlebnis festhalten.
**Vorgehen:**
1. Chat: *"Neue Erfahrung: Streit am Recyclinghof"*
2. System erstellt strukturierte Notiz mit Feldern:
- Situation
- Reaktion
- Learning
3. Verknüpfe mit relevanten Rollen: `[[rel:supports Meine Rollenlandkarte 2025#Vater]]`
### 7.3 Wissen im Graph erkunden
**Szenario:** Du willst verstehen, wie Konzepte zusammenhängen.
**Vorgehen:**
1. Wechsle zum **Graph Explorer**
2. Suche nach einem Knoten (z.B. "Projekt Alpha")
3. Klicke auf "🎯 Als Zentrum setzen"
4. Erkunde die Nachbarschaft (Abhängigkeiten, Entscheidungen, ähnliche Projekte)
### 7.4 Bestehende Notizen verbessern
**Szenario:** Eine Notiz ist unvollständig oder unvernetzt.
**Vorgehen:**
1. Öffne die Notiz im **Manuellen Editor**
2. Nutze **Intelligence-Tab** für Link-Vorschläge
3. Füge semantische Links hinzu: `[[rel:based_on Wert X]]`
4. Speichern → System indiziert neu
---
## 8. Tipps & Tricks
### 8.1 Intent-Steuerung
- **Frage mit "?":** Löst RAG-Modus aus (Wissen abrufen)
- **Aussage ohne "?":** Löst Interview-Modus aus (Wissen speichern)
- **Emotionale Wörter:** Aktivieren Empathie-Persona ("Ich fühle...", "Ich bin frustriert...")
### 8.2 Graph-Navigation
- **URL-Persistenz:** Graph-Einstellungen werden in der URL gespeichert → Lesezeichen für spezifische Ansichten
- **Deep-Links:** Verlinke präzise Abschnitte: `[[Note#Abschnitt]]` statt nur `[[Note]]`
### 8.3 Feedback nutzen
- **Regelmäßiges Feedback:** Macht das System schlauer
- **Granulares Feedback:** Bewerte einzelne Quellen, nicht nur die Gesamtantwort
- **Konsequenz:** System lernt deine Präferenzen
---
## 9. Weitere Informationen
- **Knowledge Design:** Siehe [Knowledge Design Manual](01_knowledge_design.md)
- **Authoring Guidelines:** Siehe [Authoring Guidelines](01_authoring_guidelines.md)
- **Obsidian Integration:** Siehe [Obsidian Integration Guide](01_obsidian_integration_guide.md)
- **Troubleshooting:** Siehe [Admin Operations - Troubleshooting](../04_Operations/04_admin_operations.md#33-troubleshooting-guide)
+13 -1
View File
@@ -3,7 +3,7 @@ doc_type: user_manual
audience: user, author
scope: vault, markdown, schema
status: active
version: 2.8.0
version: 2.9.1
context: "Regelwerk für das Erstellen von Notizen im Vault. Die 'Source of Truth' für Autoren."
---
@@ -208,6 +208,12 @@ Dies ist die **mächtigste** Methode. Du sagst dem System explizit, **wie** Ding
> "Daher [[rel:depends_on Qdrant]]."
> "Dieses Konzept ist [[rel:similar_to Pinecone]]."
**Deep-Links zu Abschnitten (v2.9.1):**
Du kannst auch auf spezifische Abschnitte innerhalb einer Note verlinken:
> "Siehe [[rel:based_on Mein Leitbild#P3 – Disziplin]]."
Das System trennt automatisch den Note-Namen (`Mein Leitbild`) vom Abschnitts-Namen (`P3 – Disziplin`), sodass mehrere Links zur gleichen Note möglich sind, wenn sie auf verschiedene Abschnitte zeigen.
**Gültige Relationen:**
* `depends_on`: Hängt ab von / Benötigt.
* `blocks`: Blockiert oder gefährdet (z.B. Risiko -> Projekt).
@@ -226,6 +232,12 @@ Für Zusammenfassungen am Ende einer Notiz, oder eines Absatzes:
> [[AI Agents]]
```
**Multi-Line Support (v2.9.1):**
Callout-Blocks mit mehreren Zeilen werden korrekt verarbeitet. Das System erkennt automatisch, wenn mehrere Links im gleichen Callout-Block stehen, und erstellt für jeden Link eine separate Kante (auch bei Deep-Links zu verschiedenen Sections).
**Format-agnostische De-Duplizierung:**
Wenn Kanten bereits via `[!edge]` Callout vorhanden sind, werden sie nicht mehrfach injiziert. Das System erkennt vorhandene Kanten unabhängig vom Format (Inline, Callout, Wikilink).
### 4.3 Implizite Bidirektionalität (Edger-Logik) [NEU] [PRÜFEN!]
In Mindnet musst du Kanten **nicht** manuell in beide Richtungen pflegen. Der **Edger** übernimmt die Paarbildung automatisch im Hintergrund.
+89 -21
View File
@@ -1,10 +1,10 @@
---
doc_type: concept
audience: architect, product_owner
scope: ai, router, personas, resilience
scope: ai, router, personas, resilience, agentic_rag, moe, lazy_prompts
status: active
version: 2.8.1
context: "Fachkonzept der hybriden KI-Persönlichkeit, der Provider-Kaskade und der kognitiven Resilienz (Deep Fallback)."
version: 3.1.1
context: "Fachkonzept der hybriden KI-Persönlichkeit, Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE), WP-25b Lazy-Prompt-Orchestration, Provider-Kaskade und kognitiven Resilienz (Deep Fallback)."
---
# Konzept: KI-Persönlichkeit & Router
@@ -13,13 +13,45 @@ context: "Fachkonzept der hybriden KI-Persönlichkeit, der Provider-Kaskade und
Mindnet soll nicht wie eine Suchmaschine wirken, sondern wie ein **Digitaler Zwilling**. Dazu muss das System erkennen, **was** der Nutzer will, und seine „Persönlichkeit“ sowie seine technische Infrastruktur dynamisch anpassen.
## 1. Der Hybrid Router (Das Gehirn)
## 1. Der Hybrid Router & Agentic Multi-Stream RAG (Das Gehirn)
Jede Eingabe durchläuft den **Hybrid Router**. Er entscheidet über die fachliche Strategie und die technische Ausführung.
Jede Eingabe durchläuft den **Hybrid Router**. Seit WP-25 agiert das System als **Agentic Orchestrator**, der Nutzeranfragen analysiert, in parallele Wissens-Streams aufteilt und diese zu einer kontextreichen, wertebasierten Antwort synthetisiert.
### Modus A: RAG (Retrieval Augmented Generation)
* **Intent:** Der Nutzer hat eine Frage oder ein Problem (`FACT`, `DECISION`, `EMPATHY`).
* **Aktion:** Das System sucht im Gedächtnis und generiert eine Antwort.
### Intent-basiertes Routing (WP-25)
Der Router nutzt einen **Hybrid-Modus** mit Keyword Fast-Path und LLM Slow-Path:
**Keyword Fast-Path:**
* Sofortige Erkennung von Triggern wie "Soll ich", "Wann", "Was ist"
* Reduziert Latenz durch schnelle Keyword-Erkennung ohne LLM-Call
**LLM Slow-Path:**
* Komplexe semantische Analyse für unklare Anfragen
* Nutzt `intent_router_v1` Prompt zur Klassifizierung
**Strategien:**
* **FACT_WHAT/FACT_WHEN:** Wissensabfrage (Wissen/Listen, Zeitpunkte)
* **DECISION:** Beratung (Rat, Strategie, Abwägung)
* **EMPATHY:** Reflexion (Emotionale Resonanz)
* **CODING:** Technik (Programmierung, Syntax)
* **INTERVIEW:** Datenerfassung (Wissen speichern)
### Modus A: Agentic Multi-Stream RAG (WP-25)
Anstelle einer einzelnen Suche führt das System **parallele Abfragen** in spezialisierten Wissens-Streams aus:
**Stream-Library:**
* **Values Stream:** Identität, Ethik und Prinzipien (`value`, `principle`, `belief`, `trait`, `boundary`, `need`, `motivation`)
* **Facts Stream:** Operative Daten (`project`, `decision`, `task`, `goal`, `event`, `state`)
* **Biography Stream:** Persönliche Erfahrungen (`experience`, `journal`, `profile`, `person`)
* **Risk Stream:** Hindernisse und Gefahren (`risk`, `obstacle`, `bias`)
* **Tech Stream:** Technisches Wissen (`concept`, `source`, `glossary`, `idea`, `insight`, `skill`, `habit`)
**Wissens-Synthese:**
Die Zusammenführung erfolgt über spezialisierte Templates mit expliziten Stream-Variablen (z.B. `{values_stream}`, `{risk_stream}`). Dies ermöglicht dem LLM eine differenzierte Abwägung zwischen Fakten und persönlichen Werten.
**Stream-Tracing:**
Jeder Treffer wird mit `stream_origin` markiert, um Feedback-Optimierung pro Wissensbereich zu ermöglichen.
### Modus B: Interview (Knowledge Capture)
* **Intent:** Der Nutzer will Wissen speichern (`INTERVIEW`).
@@ -27,13 +59,45 @@ Jede Eingabe durchläuft den **Hybrid Router**. Er entscheidet über die fachlic
---
## 2. Die hybride LLM-Landschaft (Resilienz-Kaskade)
## 2. Mixture of Experts (MoE) Architektur (WP-25a)
Ein intelligenter Zwilling muss jederzeit verfügbar sein. Mindnet v2.8.1 nutzt eine **dreistufige Kaskade**, um Intelligenz, Kosten und Verfügbarkeit zu optimieren:
Seit WP-25a nutzt MindNet eine **profilbasierte Experten-Steuerung** statt einer globalen Provider-Konfiguration. Jede Systemaufgabe wird einem dedizierten Profil zugewiesen, das Modell, Provider und Parameter unabhängig definiert.
1. **Stufe 1: Cloud-Speed (Turbo-Mode):** Primäre Wahl für komplexe Extraktionsaufgaben und schnelle RAG-Antworten mittels OpenRouter (Mistral-7B) oder Google Gemini (2.5-flash-lite).
### 2.1 Experten-Profile
**Zentrale Registry (`llm_profiles.yaml`):**
* **`synthesis_pro`:** Hochwertige Synthese für Chat-Antworten (Cloud)
* **`tech_expert`:** Fachspezialist für Code & Technik (Claude 3.5 Sonnet)
* **`compression_fast`:** Schnelle Kompression & Routing (Mistral 7B)
* **`ingest_validator`:** Deterministische Validierung (Temperature 0.0)
* **`identity_safe`:** Lokaler Anker (Ollama/Phi-3) für maximale Privacy
**Vorteile:**
* **Aufgabenspezifische Optimierung:** Jede Aufgabe nutzt das optimale Modell
* **Hardware-Optimierung:** Lokaler Anker für kleine Hardware-Umgebungen
* **Wartbarkeit:** Zentrale Konfiguration statt verstreuter ENV-Variablen
### 2.2 Rekursive Fallback-Kaskade
Die Profile implementieren eine **automatische Fallback-Logik**:
1. **Primäres Profil:** System versucht das angeforderte Profil (z.B. `synthesis_pro`)
2. **Fallback-Level 1:** Bei Fehler → `fallback_profile` (z.B. `synthesis_backup`)
3. **Fallback-Level 2:** Bei weiterem Fehler → nächster Fallback (z.B. `identity_safe`)
4. **Terminaler Endpunkt:** `identity_safe` hat keinen Fallback (lokales Modell als letzte Instanz)
**Schutzmechanismen:**
* **Zirkuläre Referenzen:** `visited_profiles`-Tracking verhindert Endlosschleifen
* **Background-Semaphore:** Parallele Tasks werden gedrosselt
### 2.3 Die hybride LLM-Landschaft (Legacy & MoE)
Ein intelligenter Zwilling muss jederzeit verfügbar sein. Seit WP-25a wird die Resilienz durch die **MoE Fallback-Kaskade** gewährleistet:
1. **Stufe 1: Cloud-Experten:** Spezialisierte Profile für verschiedene Aufgaben (z.B. `synthesis_pro`, `tech_expert`)
2. **Stufe 2: Quoten-Resilienz:** Erkennt das System eine Drosselung durch Cloud-Provider (HTTP 429), pausiert es kontrolliert (`LLM_RATE_LIMIT_WAIT`), führt automatisierte Retries durch und schützt so den laufenden Prozess.
3. **Stufe 3: Deep Fallback & lokale Souveränität (Ollama):** * **Technischer Fallback:** Schlagen alle Cloud-Versuche fehl, übernimmt das lokale Modell (Phi-3).
3. **Stufe 3: Lokale Souveränität (Ollama):**
* **Technischer Fallback:** Schlagen alle Cloud-Versuche fehl, übernimmt das lokale Modell (Phi-3) via `identity_safe` Profil.
* **Kognitiver Fallback (v2.11.14):** Liefert die Cloud zwar technisch eine Antwort, verweigert aber inhaltlich die Verarbeitung (Silent Refusal/Policy Violation), wird ein **Deep Fallback** erzwungen, um die Datenintegrität lokal zu retten.
@@ -45,18 +109,22 @@ Ein intelligenter Zwilling muss jederzeit verfügbar sein. Mindnet v2.8.1 nutzt
Mindnet wechselt den Hut, je nach Situation.
### 3.1 Der Berater (Strategy: DECISION)
* **Auslöser:** Fragen wie „Soll ich...?“, „Was ist besser?“.
* **Strategic Retrieval:** Lädt aktiv Notizen der Typen `value` (Werte), `goal` (Ziele) und `risk` (Risiken), auch wenn sie im Text nicht direkt vorkommen.
* **Reasoning:** *„Wäge die Fakten gegen meine Werte ab. Sei strikt bei Risiken.“*
* **Auslöser:** Fragen wie „Soll ich...?", „Was ist besser?", „Empfehlung...".
* **Multi-Stream Retrieval (WP-25):** Führt parallele Abfragen in Values Stream, Facts Stream und Risk Stream aus.
* **Wissens-Synthese:** Wägt Fakten gegen Werte ab, evaluiert Risiken und prüft Kompatibilität mit langfristiger Identität.
* **Reasoning:** *„Wäge die Fakten gegen meine Werte ab. Sei strikt bei Risiken."*
### 3.2 Der Spiegel (Strategy: EMPATHY)
* **Auslöser:** Emotionale Aussagen („Ich bin frustriert“).
* **Strategic Retrieval:** Lädt `experience` (Erfahrungen) und `belief` (Glaubenssätze).
* **Reasoning:** *„Nutze meine eigenen Erfahrungen, um die Situation einzuordnen.“*
* **Auslöser:** Emotionale Aussagen („Ich bin frustriert", „Ich fühle...", „Stress...").
* **Multi-Stream Retrieval (WP-25):** Führt parallele Abfragen in Biography Stream und Values Stream aus.
* **Wissens-Synthese:** Greift auf persönliche Erfahrungen und Werte zurück, um emotionale Resonanz zu schaffen.
* **Reasoning:** *„Nutze meine eigenen Erfahrungen, um die Situation einzuordnen."*
### 3.3 Der Bibliothekar (Strategy: FACT)
* **Auslöser:** Sachfragen („Was ist Qdrant?“).
* **Behavior:** Präzise, neutral, kurz.
### 3.3 Der Bibliothekar (Strategy: FACT_WHAT / FACT_WHEN)
* **Auslöser:** Sachfragen („Was ist...?", „Welche sind...?", „Wann...?", „Datum...").
* **Multi-Stream Retrieval (WP-25):** Führt parallele Abfragen in Facts Stream, Tech Stream und Biography Stream aus.
* **Wissens-Synthese:** Kombiniert harte Fakten mit persönlichen Erfahrungen, falls vorhanden.
* **Behavior:** Präzise, neutral, strukturiert.
---
@@ -0,0 +1,456 @@
---
doc_type: concept
audience: architect, developer
scope: architecture, design_patterns, modularization
status: active
version: 2.9.1
context: "Architektur-Patterns, Design-Entscheidungen und modulare Struktur von Mindnet. Basis für Verständnis und Erweiterungen."
---
# Architektur-Patterns & Design-Entscheidungen
Dieses Dokument beschreibt die zentralen Architektur-Patterns und Design-Entscheidungen, die Mindnet prägen. Es dient als Referenz für Entwickler und Architekten, um das System zu verstehen und konsistent zu erweitern.
## 1. Kern-Paradigmen
### 1.1 Filesystem First (Source of Truth)
**Prinzip:** Markdown-Dateien im Vault sind die einzige Quelle der Wahrheit. Die Datenbank (Qdrant) ist ein abgeleiteter Index.
**Implikationen:**
- Dateien werden immer direkt von der Festplatte gelesen (z.B. im Editor)
- Datenbank-Inhalte können aus Markdown rekonstruiert werden
- Änderungen erfolgen primär im Vault, nicht in der DB
- Die Datenbank ist ein Cache, kein primärer Speicher
**Code-Beispiele:**
- `ui_callbacks.py`: Liest Dateien direkt von Disk
- `ingestion_processor.py`: Schreibt zuerst auf Disk, dann in DB
### 1.2 Late Binding (Späte Semantik)
**Prinzip:** Struktur und Interpretation werden in Konfigurationen definiert, nicht im Code.
**Implikationen:**
- Neue Note-Typen werden in `types.yaml` definiert, nicht im Code
- Prompt-Templates sind in `prompts.yaml` konfigurierbar
- Edge-Typen werden in `edge_vocabulary.md` verwaltet
- Die "Persönlichkeit" ist Config, kein Code
**Vorteile:**
- Erweiterbarkeit ohne Code-Änderungen
- A/B-Testing von Prompt-Strategien
- Anpassung an verschiedene Use-Cases
### 1.3 Virtual Schema Layer
**Prinzip:** Markdown-Dateien benötigen nur minimale Frontmatter-Angaben. Komplexität wird zur Laufzeit injiziert.
**Beispiel:**
```yaml
# Minimal im Frontmatter
---
id: 20250101-test
title: Test
type: project
---
# Im Code wird zur Laufzeit ergänzt:
# - chunking_profile aus types.yaml
# - retriever_weight aus types.yaml
# - edge_defaults aus types.yaml
```
**Vorteile:**
- Robuste Markdown-Dateien (weniger Breaking Changes)
- Zentrale Verwaltung von Logik
- Einfache Migration zwischen Versionen
---
## 2. Modulare Architektur (WP-14)
### 2.1 Paket-Struktur
Seit WP-14 ist die Core-Logik in spezialisierte Pakete unterteilt:
```
app/core/
├── chunking/ # Text-Segmentierung
│ ├── chunking_strategies.py # Sliding/Heading-Strategien
│ ├── chunking_processor.py # Orchestrierung
│ └── chunking_propagation.py # Edge-Vererbung
├── database/ # Qdrant-Infrastruktur
│ ├── qdrant.py # Client & Config
│ └── qdrant_points.py # Point-Mapping
├── graph/ # Graph-Logik
│ ├── graph_subgraph.py # Expansion
│ └── graph_weights.py # Scoring
├── ingestion/ # Import-Pipeline
│ ├── ingestion_processor.py # Two-Pass Workflow
│ └── ingestion_validation.py # Mistral-safe Parsing
├── parser/ # Markdown-Parsing
│ ├── parsing_markdown.py # Frontmatter/Body
│ └── parsing_scanner.py # File-Scan
└── retrieval/ # Suche & Scoring
├── retriever.py # Orchestrator
└── retriever_scoring.py # Mathematik
```
### 2.2 Design-Pattern: Proxy-Adapter (Abwärtskompatibilität)
**Problem:** Nach WP-14 Modularisierung müssen alte Import-Pfade weiter funktionieren.
**Lösung:** Proxy-Module leiten Anfragen an neue Pakete weiter.
**Beispiel:**
```python
# app/core/retriever.py (Proxy)
from .retrieval.retriever import (
Retriever, hybrid_retrieve, semantic_retrieve
)
__all__ = ["Retriever", "hybrid_retrieve", "semantic_retrieve"]
```
**Vorteile:**
- Keine Breaking Changes für bestehenden Code
- Graduelle Migration möglich
- Alte Scripts funktionieren weiter
### 2.3 Design-Pattern: Singleton (Edge Registry)
**Problem:** Edge Registry muss konsistent über alle Services sein.
**Lösung:** Singleton-Pattern mit Lazy Loading.
**Code:**
```python
# app/services/edge_registry.py
class EdgeRegistry:
_instance = None
def __new__(cls):
if cls._instance is None:
cls._instance = super().__new__(cls)
return cls._instance
```
**Vorteile:**
- Einheitliche Validierung
- Keine Duplikation von Vokabular-Daten
- Thread-safe Initialisierung
---
## 3. Asynchrone Verarbeitung
### 3.1 Background Tasks Pattern
**Problem:** Ingestion kann lange dauern (LLM-Calls, Embeddings). Blockiert API nicht.
**Lösung:** FastAPI Background Tasks für non-blocking Verarbeitung.
**Flow:**
1. API empfängt Request (`/ingest/save`)
2. Datei wird sofort auf Disk geschrieben
3. API antwortet mit `status: "queued"`
4. Background Task startet Ingestion asynchron
5. User kann weiterarbeiten
**Code:**
```python
@router.post("/save")
async def save_note(req: SaveRequest, background_tasks: BackgroundTasks):
# Sofortige Persistenz
write_to_disk(req.markdown_content)
# Async Processing
background_tasks.add_task(run_ingestion_task, ...)
return SaveResponse(status="queued", ...)
```
**Vorteile:**
- Keine Timeouts bei großen Dateien
- Bessere User Experience
- System bleibt responsiv
### 3.2 Traffic Control (Semaphore Pattern)
**Problem:** Parallele LLM-Calls können System überlasten.
**Lösung:** Semaphore begrenzt parallele Hintergrund-Tasks.
**Code:**
```python
# app/services/llm_service.py
background_semaphore = asyncio.Semaphore(
settings.BACKGROUND_LIMIT # Default: 2
)
async def generate(...):
if priority == "background":
async with background_semaphore:
return await _call_llm(...)
else: # realtime
return await _call_llm(...) # Keine Limitierung
```
**Vorteile:**
- Schutz vor API-Quoten-Überschreitung
- Stabiler Betrieb bei hoher Last
- Priorisierung von Echtzeit-Anfragen
---
## 4. Resilienz-Patterns
### 4.1 Provider-Kaskade (Fallback-Kette)
**Problem:** Cloud-Provider können ausfallen oder Quoten überschreiten.
**Lösung:** Dreistufige Kaskade mit intelligentem Fallback.
**Stufen:**
1. **Cloud (OpenRouter/Gemini):** Schnell, aber abhängig von Provider
2. **Rate-Limit-Handling:** Automatische Retries bei HTTP 429
3. **Lokaler Fallback (Ollama):** Langsam, aber immer verfügbar
**Code:**
```python
# app/services/llm_service.py
async def generate(...):
try:
return await _call_cloud(...)
except RateLimitError:
await asyncio.sleep(LLM_RATE_LIMIT_WAIT)
return await _call_cloud(...) # Retry
except Exception:
return await _call_ollama(...) # Fallback
```
**Vorteile:**
- Hohe Verfügbarkeit
- Kostenoptimierung (Cloud für Speed, Lokal für Fallback)
- Resilienz gegen Provider-Ausfälle
### 4.2 Deep Fallback (Kognitiver Fallback)
**Problem:** Cloud liefert technisch erfolgreiche, aber inhaltlich leere Antworten (Silent Refusal).
**Lösung:** Validierung der Antwort-Qualität, nicht nur HTTP-Status.
**Code:**
```python
response = await _call_cloud(...)
if is_valid_json(response):
return response
else:
# Deep Fallback: Cloud hat blockiert, lokaler Fallback
return await _call_ollama(...)
```
**Vorteile:**
- Erkennung von Policy-Violations
- Datenintegrität trotz Cloud-Filter
- Lokale Souveränität
---
## 5. Datenfluss-Patterns
### 5.1 Two-Pass Workflow (WP-15b)
**Problem:** Smart Edge Validation benötigt globalen Kontext (alle Notizen).
**Lösung:** Zwei-Phasen-Import mit Pre-Scan.
**Pass 1: Pre-Scan**
- Schnelles Scannen aller Dateien
- Aufbau von `LocalBatchCache` (IDs, Titel, Summaries)
- Keine LLM-Calls
**Pass 2: Semantic Processing**
- Nur für geänderte Dateien
- Binäre Validierung gegen Cache
- Effiziente Nutzung von LLM-Quoten
**Vorteile:**
- Reduktion von LLM-Calls (nur Validierung, keine Extraktion)
- Konsistente Validierung (globaler Kontext)
- Schnellerer Import
### 5.2 Idempotenz-Pattern
**Prinzip:** Mehrfache Imports derselben Datei führen zum gleichen Ergebnis.
**Mechanismen:**
- **Deterministische IDs:** UUIDv5 basierend auf Datei-Inhalt
- **Hash-basierte Change Detection:** Multi-Hash für `body` und `full`
- **Deduplizierung:** Kanten werden anhand Identität erkannt
**Code:**
```python
# Deterministische ID
note_id = uuid.uuid5(NAMESPACE_URL, f"{file_path}#{content_hash}")
# Change Detection
if current_hash == stored_hash:
skip_processing() # Idempotent
```
**Vorteile:**
- Sicherheit bei Re-Imports
- Keine Duplikate
- Konsistente Datenbank
---
## 6. Frontend-Patterns
### 6.1 Active Inspector Pattern
**Problem:** Graph-Re-Renders bei Knoten-Selektion führen zu Flackern.
**Lösung:** CSS-Klassen statt State-Änderungen für Selektion.
**Code:**
```python
# ui_graph_cytoscape.py
stylesheet = [
{
"selector": ".inspected",
"style": {"border-width": 6, "border-color": "#FFC300"}
}
]
# Selektion ändert nur CSS-Klasse, nicht React-Key
```
**Vorteile:**
- Stabiles UI (kein Re-Render)
- Bessere Performance
- Smooth User Experience
### 6.2 Resurrection Pattern
**Problem:** Streamlit vergisst Eingaben bei Re-Runs.
**Lösung:** Aggressive Synchronisation in `session_state`.
**Code:**
```python
# ui_editor.py
if widget_key not in st.session_state:
st.session_state[widget_key] = restore_from_data_key()
```
**Vorteile:**
- Texteingaben überleben Tab-Wechsel
- Keine Datenverluste
- Bessere UX
---
## 7. Erweiterbarkeit: "Teach-the-AI" Paradigma
Mindnet lernt durch **Konfiguration**, nicht durch Training.
### 7.1 Drei-Ebenen-Erweiterung
**1. Daten-Ebene (`types.yaml`):**
```yaml
risk:
retriever_weight: 0.90
edge_defaults: ["blocks"]
```
**2. Strategie-Ebene (`decision_engine.yaml`):**
```yaml
DECISION:
inject_types: ["value", "risk"]
```
**3. Kognitive Ebene (`prompts.yaml`):**
```yaml
risk_definition:
ollama: "Ein Risiko ist eine potenzielle Gefahr..."
```
**Vorteile:**
- Keine Code-Änderungen nötig
- Schnelle Iteration
- A/B-Testing möglich
---
## 8. Design-Entscheidungen & Trade-offs
### 8.1 Qdrant als Vektor-DB
**Entscheidung:** Qdrant statt Pinecone/Weaviate
**Gründe:**
- Self-hosted (Privacy First)
- Open Source
- Gute Performance bei lokaler Installation
**Trade-off:** Mehr Wartungsaufwand als Managed Service
### 8.2 Hybrid Retrieval (Semantik + Graph)
**Entscheidung:** Kombination von Vektor-Suche und Graph-Expansion
**Gründe:**
- Semantik findet ähnliche Inhalte
- Graph findet strukturelle Verbindungen
- Kombination liefert bessere Relevanz
**Trade-off:** Höhere Komplexität, mehr Berechnungsaufwand
### 8.3 Background Tasks statt Queue-System
**Entscheidung:** FastAPI Background Tasks statt Redis/RabbitMQ
**Gründe:**
- Einfacher Setup (keine zusätzliche Infrastruktur)
- Ausreichend für Single-User-Szenario
- Weniger Moving Parts
**Trade-off:** Keine Persistenz bei Server-Neustart (Tasks gehen verloren)
---
## 9. Konsistenz-Garantien
### 9.1 Deterministische IDs
**Prinzip:** UUIDv5 basierend auf Datei-Inhalt
**Vorteile:**
- Reproduzierbare IDs
- Keine Duplikate bei Re-Import
- Graph ist aus Markdown rekonstruierbar
### 9.2 Provenance-Hierarchie
**Prinzip:** Kanten haben Qualitätsstufen (explicit > smart > rule)
**Vorteile:**
- Menschliche Intention hat Vorrang
- System-Heuristiken können überschrieben werden
- Transparente Gewichtung
---
## 10. Weitere Informationen
- **Vision & Strategie:** Siehe [Vision & Strategie](../00_General/00_vision_and_strategy.md)
- **Graph-Logik:** Siehe [Graph-Logik](02_concept_graph_logic.md)
- **KI-Persönlichkeit:** Siehe [KI-Persönlichkeit](02_concept_ai_personality.md)
- **Developer Guide:** Siehe [Developer Guide](../05_Development/05_developer_guide.md)
---
**Letzte Aktualisierung:** 2025-01-XX
**Version:** 2.9.1
+44 -5
View File
@@ -3,8 +3,8 @@ doc_type: concept
audience: architect, product_owner
scope: graph, logic, provenance
status: active
version: 2.7.0
context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik und WP-22 Scoring-Prinzipien."
version: 2.9.1
context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik, WP-15c Multigraph-Support und WP-22 Scoring-Prinzipien."
---
# Konzept: Die Graph-Logik
@@ -59,7 +59,7 @@ Um eine konsistente mathematische Gewichtung zu garantieren, werden alle Kanten
### 2.2 Provenance (Herkunft & Vertrauen)
Nicht alle Kanten sind gleich viel wert. Mindnet unterscheidet drei Qualitätsstufen (**Provenance**), um bei der Berechnung des Edge-Bonus Prioritäten zu setzen.
Nicht alle Kanten sind gleich viel wert. Mindnet unterscheidet mehrere Qualitätsstufen (**Provenance**), um bei der Berechnung des Edge-Bonus Prioritäten zu setzen.
**1. Explicit (Der Mensch hat es gesagt)**
* *Quelle:* Inline-Links (`[[rel:...]]`) oder Wikilinks im Text.
@@ -76,6 +76,19 @@ Nicht alle Kanten sind gleich viel wert. Mindnet unterscheidet drei Qualitätsst
* *Vertrauen:* **Niedrig (0.7)**.
* *Bedeutung:* Systemseitige Heuristik. Diese Verbindungen dienen der Entdeckung neuer Pfade, haben aber weniger Gewicht als explizite Links.
**4. Structure (System-interne Verkettung)**
* *Quelle:* Automatische Struktur-Kanten (`belongs_to`, `next`, `prev`).
* *Vertrauen:* **Hoch (1.0)**.
* *Bedeutung:* Diese Kanten werden ausschließlich durch interne Prozesse erzeugt und sind durch die **Provenance Firewall** geschützt. Sie können weder durch Nutzer noch durch KI manipuliert werden.
### 2.3 Provenance Firewall (WP-15c)
Die **Edge Registry** (v0.8.0) implementiert eine strikte Trennung zwischen System-Kanten und Inhalts-Kanten:
* **Geschützte System-Kanten:** `next`, `prev`, `belongs_to` dürfen nur mit `provenance="structure"` gesetzt werden.
* **Blockierung:** Alle anderen Provenienzen (`explicit`, `semantic_ai`, `inherited`, `global_pool`, `rule`) werden bei System-Kanten blockiert und auf `related_to` zurückgesetzt.
* **Zweck:** Sichert die Graph-Integrität und verhindert Manipulationen an der internen Struktur.
---
## 3. Matrix-Logik (Kontext-Sensitivität)
@@ -118,8 +131,34 @@ Der Intent-Router injiziert spezifische Multiplikatoren für kanonische Typen:
---
## 6. Idempotenz & Konsistenz
## 6. Section-basierte Links & Multigraph-Support
Seit v2.9.1 unterstützt Mindnet **Deep-Links** zu spezifischen Abschnitten innerhalb einer Note.
### 6.1 Link-Parsing & Self-Links (WP-15c)
Die Logik erkennt nun präzise **Obsidian-Anker** (`[[Note#Section]]`) und **Self-Links** (`[[#Section]]`):
* **Obsidian-Anker:** `[[Note#Section]]` wird in `target_id="Note"` und `target_section="Section"` aufgeteilt.
* **Self-Links:** `[[#Section]]` wird zu `target_id="current_note_id"` und `target_section="Section"` aufgelöst.
* **`target_id`:** Enthält nur den Note-Namen (z.B. "Mein Leitbild")
* **`target_section`:** Enthält den Abschnitts-Namen (z.B. "P3 – Disziplin")
**Vorteil:** Verhindert "Phantom-Knoten", die durch das Einbeziehen des Anchors in die `target_id` entstanden wären. Ermöglicht präzise Verlinkung innerhalb derselben Note.
### 6.2 Multigraph-Support
Die Edge-ID enthält nun einen `variant`-Parameter (die Section), sodass mehrere Kanten zwischen denselben Knoten existieren können, wenn sie auf verschiedene Sections zeigen:
* `[[Note#Section1]]` → Edge-ID: `src->tgt:kind@Section1`
* `[[Note#Section2]]` → Edge-ID: `src->tgt:kind@Section2`
### 6.3 Semantische Deduplizierung
Die Deduplizierung basiert auf dem `src->tgt:kind@sec` Key, um sicherzustellen, dass identische Links (gleiche Quelle, Ziel, Typ und Section) nicht mehrfach erstellt werden.
---
## 7. Idempotenz & Konsistenz
Das System garantiert fachliche Konsistenz auch bei mehrfachen Importen.
* **Stabile IDs:** Deterministische IDs verhindern Duplikate bei Re-Imports.
* **Deduplizierung:** Kanten werden anhand ihrer Identität erkannt. Die "stärkere" Provenance gewinnt.
* **Deduplizierung:** Kanten werden anhand ihrer Identität (inkl. Section) erkannt. Die "stärkere" Provenance gewinnt.
* **Format-agnostische Erkennung:** Kanten werden unabhängig vom Format (Inline, Callout, Wikilink) erkannt, um Dopplungen zu vermeiden.
@@ -0,0 +1,454 @@
---
doc_type: technical_reference
audience: developer, integrator
scope: api, endpoints, integration, agentic_rag
status: active
version: 2.9.3
context: "Vollständige API-Referenz für alle Mindnet-Endpunkte inklusive WP-25 Agentic Multi-Stream RAG. Basis für Integration und Entwicklung."
---
# API Reference
Diese Dokumentation beschreibt alle verfügbaren API-Endpunkte von Mindnet. Die API basiert auf FastAPI und nutzt automatische OpenAPI-Dokumentation (verfügbar unter `/docs`).
## Basis-URL
```
http://localhost:8001 # Production
http://localhost:8002 # Development
```
## Health Check
### `GET /healthz`
Prüft den Status der API und der Verbindung zu Qdrant.
**Response:**
```json
{
"status": "ok",
"qdrant": "http://localhost:6333",
"prefix": "mindnet"
}
```
---
## Query Endpoints
### `POST /query`
Führt eine hybride oder semantische Suche im Wissensgraph durch.
**Request Body:**
```json
{
"query": "Was ist Mindnet?",
"mode": "hybrid", // "hybrid" oder "semantic"
"top_k": 10,
"expand_depth": 1,
"explain": true
}
```
**Response:**
```json
{
"query_id": "uuid-v4",
"hits": [
{
"chunk_id": "uuid",
"note_id": "uuid",
"text": "Auszug...",
"score": 0.85,
"explanation": {
"reasons": [...]
}
}
],
"stats": {
"total_hits": 10,
"query_time_ms": 45
}
}
```
**Hinweis:** Das Feedback-Logging erfolgt asynchron im Hintergrund (Background Tasks).
---
## Chat Endpoints
### `POST /chat/`
Hauptendpunkt für RAG-Chat und Interview-Modus. Unterstützt Streaming.
**Request Body:**
```json
{
"message": "Was ist Mindnet?",
"history": [], // Optional: Chat-Verlauf
"stream": true // Optional: SSE-Streaming
}
```
**Response (Non-Streaming):**
```json
{
"query_id": "uuid",
"answer": "Mindnet ist ein persönliches KI-Gedächtnis...",
"sources": [
{
"node_id": "uuid",
"note_id": "uuid",
"semantic_score": 0.85,
"total_score": 0.92,
"stream_origin": "values_stream", // WP-25: Ursprungs-Stream
"explanation": {...}
}
],
"latency_ms": 450,
"intent": "DECISION", // WP-25: Gewählte Strategie
"intent_source": "Keyword (FastPath)" // WP-25: Quelle der Intent-Erkennung
}
```
**Response (Streaming):**
Server-Sent Events (SSE) mit Chunks der Antwort.
**Intent-Typen (WP-25):**
- `FACT_WHAT`: Wissensabfrage (Wissen/Listen)
- `FACT_WHEN`: Zeitpunkte (Termine, Daten)
- `DECISION`: Entscheidungsfrage (Beratung, Strategie)
- `EMPATHY`: Emotionale Anfrage (Reflexion)
- `CODING`: Technische Anfrage (Programmierung)
- `INTERVIEW`: Wissen erfassen (Datenerfassung)
**Stream-Tracing (WP-25):**
Jeder Treffer in `sources` enthält `stream_origin`, um die Zuordnung zum Quell-Stream zu ermöglichen (z.B. "values_stream", "facts_stream", "risk_stream").
---
## Graph Endpoints
### `GET /graph/{note_id}`
Lädt den Subgraphen um eine Note herum.
**Query Parameters:**
- `depth` (int, default: 1): Tiefe der Graph-Expansion
- `edge_types` (List[str], optional): Filter für Kanten-Typen
**Response:**
```json
{
"center_note_id": "uuid",
"nodes": [
{
"id": "uuid",
"type": "project",
"title": "Projekt Alpha",
"tags": ["ki"],
"in_degree": 5,
"out_degree": 3
}
],
"edges": [
{
"id": "uuid->uuid:depends_on",
"kind": "depends_on",
"source": "uuid",
"target": "uuid",
"target_section": "P3 – Disziplin", // Optional: Abschnitts-Name bei Deep-Links
"weight": 1.4,
"direction": "out",
"provenance": "explicit",
"confidence": 1.0
}
],
"stats": {
"node_count": 10,
"edge_count": 15
}
}
```
---
## Ingest Endpoints
### `POST /ingest/analyze`
Analysiert einen Text-Draft und liefert Link-Vorschläge (Intelligence-Feature).
**Request Body:**
```json
{
"text": "Markdown-Text...",
"type": "concept" // Optional: Notiz-Typ
}
```
**Response:**
```json
{
"suggestions": [
{
"text": "Mindnet",
"type": "exact_match",
"note_id": "uuid",
"confidence": 0.95
},
{
"text": "KI-Gedächtnis",
"type": "semantic",
"note_id": "uuid",
"confidence": 0.82
}
]
}
```
### `POST /ingest/save`
Speichert eine Notiz und startet die Ingestion im Hintergrund (WP-14: Background Tasks).
**Request Body:**
```json
{
"markdown_content": "---\nid: ...\n---\n# Titel\n...",
"filename": "meine-notiz.md", // Optional
"folder": "00_Inbox" // Optional, default: "00_Inbox"
}
```
**Response:**
```json
{
"status": "queued",
"file_path": "00_Inbox/meine-notiz.md",
"note_id": "pending",
"message": "Speicherung & Hybrid-KI-Analyse (WP-20) im Hintergrund gestartet.",
"stats": {
"chunks": -1, // -1 = Async Processing
"edges": -1
}
}
```
**Wichtig:**
- Die Datei wird sofort auf der Festplatte gespeichert
- Die Ingestion (Chunking, Embedding, Smart Edges) läuft asynchron im Hintergrund
- Dies verhindert Timeouts bei großen Dateien oder langsamen LLM-Calls
---
## Feedback Endpoints
### `POST /feedback`
Nimmt explizites User-Feedback entgegen (WP-04c).
**Request Body:**
```json
{
"query_id": "uuid",
"rating": 5, // 1-5 Sterne
"feedback_type": "global", // "global" oder "granular"
"chunk_id": "uuid" // Optional für granular feedback
}
```
**Response:**
```json
{
"status": "recorded",
"query_id": "uuid"
}
```
---
## Tools Endpoints
### `GET /tools/ollama`
Liefert JSON-Schemas für die Integration als Tools in externe Agenten (Ollama, OpenAI, etc.).
**Response:**
```json
{
"tools": [
{
"type": "function",
"function": {
"name": "mindnet_query",
"description": "Hybrid-Retrieval über mindnet (Semantik + Edges).",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Freitext-Query"
},
"top_k": {
"type": "integer",
"default": 10,
"minimum": 1,
"maximum": 50
}
}
}
}
},
{
"type": "function",
"function": {
"name": "mindnet_subgraph",
"description": "Gibt die Nachbarschaft (Edges) einer Note/Seed-ID zurück.",
"parameters": {
"type": "object",
"properties": {
"note_id": {
"type": "string"
},
"depth": {
"type": "integer",
"default": 1,
"minimum": 0,
"maximum": 3
}
},
"required": ["note_id"]
}
}
}
]
}
```
**Verwendung:** Diese Schemas können direkt in Ollama-Function-Calling oder OpenAI-Tools integriert werden.
---
## Admin Endpoints
### `GET /admin/stats`
Liefert Statistiken über die Qdrant-Collections und die aktuelle Konfiguration.
**Response:**
```json
{
"collections": {
"notes": {
"name": "mindnet_notes",
"count": 150
},
"chunks": {
"name": "mindnet_chunks",
"count": 1250
},
"edges": {
"name": "mindnet_edges",
"count": 3200
}
},
"config": {
"qdrant": "http://localhost:6333",
"prefix": "mindnet",
"vector_size": 768,
"distance": "Cosine",
"retriever": {
"w_sem": 0.70,
"w_edge": 0.25,
"w_cent": 0.05,
"top_k": 10,
"expand_depth": 1
}
}
}
```
**Hinweis:** Dieser Endpunkt ist optional und kann deaktiviert sein, wenn der `admin`-Router nicht geladen wird.
---
## Fehlerbehandlung
Alle Endpunkte verwenden standardisierte HTTP-Status-Codes:
- `200 OK`: Erfolgreiche Anfrage
- `201 Created`: Ressource erfolgreich erstellt
- `400 Bad Request`: Ungültige Anfrage (z.B. fehlende Parameter)
- `500 Internal Server Error`: Server-Fehler
**Fehler-Response-Format:**
```json
{
"detail": "Fehlerbeschreibung"
}
```
---
## Rate Limiting & Timeouts
- **Chat-Endpunkte:** Keine Retries (max_retries=0) für schnelle Fallback-Kaskade
- **Ingest-Endpunkte:** Background Tasks verhindern Timeouts
- **Query-Endpunkte:** Standard-Timeout konfigurierbar via `MINDNET_API_TIMEOUT`
---
## OpenAPI Dokumentation
Die vollständige interaktive API-Dokumentation ist verfügbar unter:
- Swagger UI: `http://localhost:8001/docs`
- ReDoc: `http://localhost:8001/redoc`
- OpenAPI JSON: `http://localhost:8001/openapi.json`
---
## Integration Beispiele
### Python (requests)
```python
import requests
# Query
response = requests.post(
"http://localhost:8001/query",
json={"query": "Was ist Mindnet?", "top_k": 5}
)
print(response.json())
# Chat
response = requests.post(
"http://localhost:8001/chat/",
json={"message": "Erkläre mir Mindnet"}
)
print(response.json())
```
### cURL
```bash
# Health Check
curl http://localhost:8001/healthz
# Query
curl -X POST http://localhost:8001/query \
-H "Content-Type: application/json" \
-d '{"query": "Was ist Mindnet?", "top_k": 5}'
```
---
## Weitere Informationen
- **Chat-Backend Details:** Siehe [Chat Backend Dokumentation](03_tech_chat_backend.md)
- **Ingestion-Pipeline:** Siehe [Ingestion Pipeline](03_tech_ingestion_pipeline.md)
- **Retrieval & Scoring:** Siehe [Retrieval & Scoring](03_tech_retrieval_scoring.md)
@@ -1,57 +1,174 @@
---
doc_type: technical_reference
audience: developer, architect
scope: backend, chat, llm_service, traffic_control, resilience
scope: backend, chat, llm_service, traffic_control, resilience, agentic_rag, moe, lazy_prompts
status: active
version: 2.8.1
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.3.6) und der WP-20 Resilienz-Logik."
version: 3.1.1
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.5.5), WP-25 Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE), WP-25b Lazy-Prompt-Orchestration und WP-20 Resilienz-Logik."
---
# Chat Backend & Traffic Control
# Chat Backend & Agentic Multi-Stream RAG
## 1. Hybrid Router (Decision Engine)
## 1. Hybrid Router & Intent-basiertes Routing (WP-25)
Der zentrale Einstiegspunkt für jede Chatanfrage ist der **Hybrid Router** (`app/routers/chat.py`). Er entscheidet dynamisch über die Strategie und nutzt den `LLMService` zur provider-agnostischen Generierung.
Der zentrale Einstiegspunkt für jede Chatanfrage ist der **Hybrid Router** (`app/routers/chat.py`). Seit WP-25 agiert das System als **Agentic Orchestrator**, der Nutzeranfragen analysiert, in parallele Wissens-Streams aufteilt und diese zu einer kontextreichen, wertebasierten Antwort synthetisiert.
### 1.1 Intent-Erkennung (Logik)
### 1.1 Intent-Erkennung (Hybrid-Modus - WP-25b)
Der Router prüft den Input in drei Stufen (Wasserfall-Prinzip):
Der Router nutzt einen **Hybrid-Modus** mit Keyword-Fast-Path und LLM-Slow-Path:
1. **Question Detection (Regelbasiert):**
* Prüfung auf Vorhandensein von `?` oder W-Wörtern (Wer, Wie, Was, Soll ich).
* Wenn positiv: **RAG Modus** (Interview wird blockiert).
2. **Keyword Scan (Fast Path):**
* Lädt `types.yaml` (Objekte) und `decision_engine.yaml` (Handlungen).
* Wenn Match (z.B. "Projekt" + "neu"): **INTERVIEW Modus**.
3. **LLM Fallback (Slow Path):**
* Wenn unklar: Anfrage an LLM zur Klassifizierung mittels `router_prompt`.
1. **Keyword Fast-Path (Sofortige Erkennung):**
* Prüft `trigger_keywords` aus `decision_engine.yaml` (z.B. "Soll ich", "Wann", "Was ist").
* Wenn Match: Sofortige Intent-Zuordnung ohne LLM-Call.
* **Strategien:** FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW.
2. **Type Keywords (Interview-Modus):**
* Lädt `types.yaml` und prüft `detection_keywords` für Objekt-Erkennung.
* Wenn Match und keine Frage: **INTERVIEW Modus** (Datenerfassung).
3. **LLM Slow-Path (Semantische Analyse - WP-25b):**
* Wenn unklar: Anfrage an `DecisionEngine._determine_strategy()` zur LLM-basierten Klassifizierung.
* **Lazy-Prompt-Loading:** Nutzt `prompt_key="intent_router_v1"` mit `variables={"query": query}`
* **Ultra-robustes Parsing:** Regex-basierter Intent-Parser bereinigt Modell-Artefakte (z.B. `CODING[/S]` → `CODING`)
* **Fallback:** Bei unklarem Intent → `FACT_WHAT`
### 1.2 Prompt-Auflösung (Bulletproof Resolution)
### 1.2 Mixture of Experts (MoE) Architektur (WP-25a)
Um Kompatibilitätsprobleme mit verschachtelten YAML-Prompts zu vermeiden, nutzt der Router die Methode `llm.get_prompt()`. Diese implementiert eine **Provider-Kaskade**:
* **Spezifischer Provider:** Das System sucht zuerst nach einem Prompt für den aktiv konfigurierten Provider (z.B. `openrouter`).
* **Cloud-Stil Fallback:** Existiert dieser nicht, erfolgt ein Fallback auf das `gemini`-Template.
* **Basis-Fallback:** Als letzte Instanz wird das `ollama`-Template geladen.
* **String-Garantie:** Die Methode garantiert die Rückgabe eines Strings (selbst bei verschachtelten YAML-Dicts), was 500-Fehler bei String-Operationen wie `.replace()` oder `.format()` verhindert.
Seit WP-25a nutzt MindNet eine **profilbasierte Experten-Steuerung** statt einer globalen Provider-Konfiguration. Jede Systemaufgabe wird einem dedizierten Profil zugewiesen:
### 1.3 RAG Flow (Technisch)
**Profil-Registry (`llm_profiles.yaml`):**
* **`synthesis_pro`:** Hochwertige Synthese für Chat-Antworten
* **`tech_expert`:** Fachspezialist für Code & Technik
* **`compression_fast`:** Schnelle Kompression & Routing
* **`ingest_validator`:** Deterministische Validierung (Temperature 0.0)
* **`identity_safe`:** Lokaler Anker (Ollama/Phi-3) für maximale Privacy
Wenn der Intent `FACT` oder `DECISION` ist, wird folgender Flow ausgeführt:
**Rekursive Fallback-Kaskade:**
Der `LLMService` (v3.5.2) implementiert eine automatische Fallback-Logik:
1. Versucht primäres Profil (z.B. `synthesis_pro`)
2. Bei Fehler → `fallback_profile` (z.B. `synthesis_backup`)
3. Bei weiterem Fehler → nächster Fallback (z.B. `identity_safe`)
4. Schutz gegen Zirkel-Referenzen via `visited_profiles`-Tracking
1. **Pre-Processing:** Query Rewriting (optional).
2. **Context Enrichment:**
* Abruf via `retriever.py` (Hybrid Search).
* Integration von **Edge Boosts** aus der `decision_engine.yaml` zur Beeinflussung der Graph-Gewichtung.
* Injection von Metadaten (`[TYPE]`, `[SCORE]`) in den Prompt.
3. **Prompt Construction:** Assembly aus System-Prompt (Persona) + Context + Query.
4. **Streaming:** LLM-Antwort wird via **SSE (Server-Sent Events)** an den Client gestreamt.
5. **Post-Processing:** Anhängen des `Explanation` Layers (JSON-Breakdown) an das Ende des Streams.
**Integration:**
* **Intent-Routing:** Nutzt `router_profile` (z.B. `compression_fast`)
* **Stream-Kompression:** Nutzt `compression_profile` pro Stream
* **Synthese:** Nutzt `llm_profile` aus Strategie-Konfiguration
* **Ingestion:** Nutzt `ingest_validator` für binäre Validierungen
### 1.3 Hierarchisches Prompt-Resolution-System (WP-25b)
Seit WP-25b nutzt MindNet eine **dreistufige hierarchische Prompt-Auflösung** mit Lazy-Loading. Prompts werden erst im Moment des Modellaustauschs geladen, basierend auf dem exakt aktiven Modell.
**Hierarchische Auflösung (`llm_service.py` v3.5.5):**
1. **Level 1 (Modell-ID):** Suche nach exakten Übereinstimmungen für die Modell-ID (z.B. `google/gemini-2.0-flash-exp:free`).
* **Vorteil:** Modell-spezifische Optimierungen (z.B. für Gemini 2.0, Llama 3.3, Qwen 2.5)
* **Logging:** `🎯 [PROMPT-TRACE] Level 1 Match: Model-specific`
2. **Level 2 (Provider):** Fallback auf allgemeine Provider-Anweisungen (z.B. `openrouter` oder `ollama`).
* **Vorteil:** Bewährte Standards aus v3.1.2 bleiben erhalten
* **Logging:** `📡 [PROMPT-TRACE] Level 2 Match: Provider-fallback`
3. **Level 3 (Default):** Globaler Sicherheits-Satz zur Vermeidung von Fehlern bei unbekannten Konfigurationen.
* **Fallback-Kette:** `default` → `gemini` → `ollama` → `""`
* **Logging:** `⚓ [PROMPT-TRACE] Level 3 Match: Global Default`
**Lazy-Prompt-Orchestration:**
* **Lazy Loading:** Prompts werden erst zur Laufzeit geladen, wenn das aktive Modell bekannt ist
* **Parameter:** `prompt_key` und `variables` statt vorformatierter Strings
* **Vorteil:** Maximale Resilienz bei Modell-Fallbacks (Cloud → Local)
* **Traceability:** Vollständige Transparenz über genutzte Instruktionen via `[PROMPT-TRACE]` Logs
**String-Garantie:**
Die Methode garantiert die Rückgabe eines Strings (selbst bei verschachtelten YAML-Dicts), was 500-Fehler bei String-Operationen wie `.replace()` oder `.format()` verhindert.
### 1.4 Multi-Stream Retrieval (WP-25)
Anstelle einer einzelnen Suche führt die `DecisionEngine` nun **parallele Abfragen** in spezialisierten Streams aus:
**Stream-Library (definiert in `decision_engine.yaml`):**
* **Values Stream:** Extrahiert Identität, Ethik und Prinzipien (`value`, `principle`, `belief`, etc.).
* **Facts Stream:** Liefert operative Daten zu Projekten, Tasks und Status (`project`, `decision`, `task`, etc.).
* **Biography Stream:** Greift auf persönliche Erfahrungen und Journal-Einträge zu (`experience`, `journal`, `profile`).
* **Risk Stream:** Identifiziert Hindernisse und potenzielle Gefahren (`risk`, `obstacle`, `bias`).
* **Tech Stream:** Bündelt technisches Wissen, Code und Dokumentation (`concept`, `source`, `glossary`, etc.).
**Stream-Konfiguration:**
* Jeder Stream nutzt individuelle **Edge-Boosts** (z.B. `guides: 3.0` für Values Stream).
* **Filter-Types** sind strikt mit `types.yaml` (v2.7.0) synchronisiert.
* **Query-Templates** transformieren die ursprüngliche Anfrage für spezialisierte Suche.
**Parallele Ausführung:**
* `asyncio.gather()` führt alle aktiven Streams gleichzeitig aus.
* **Stream-Tracing:** Jeder Treffer wird mit `stream_origin` markiert für Feedback-Optimierung.
* **Fehlerbehandlung:** Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage.
### 1.5 Pre-Synthesis Kompression (WP-25a)
Wissens-Streams, die den Schwellenwert (`compression_threshold`) überschreiten, werden **asynchron verdichtet**, bevor sie die Synthese erreichen:
**Kompression-Logik:**
* **Schwellenwert:** Konfigurierbar pro Stream (z.B. 2500 Zeichen für Values Stream)
* **Profil:** Nutzt `compression_profile` (z.B. `compression_fast` für schnelle Zusammenfassung)
* **Parallelisierung:** Mehrere Streams können gleichzeitig komprimiert werden
* **Fehlerbehandlung:** Kompressions-Fehler blockieren nicht die Synthese (Original-Content wird verwendet)
**Vorteile:**
* Reduziert Token-Verbrauch bei langen Streams
* Beschleunigt Synthese durch kürzere Kontexte
* Erhält Relevanz durch intelligente Zusammenfassung
### 1.6 Wissens-Synthese (WP-25/25a)
Die Zusammenführung der Daten erfolgt über spezialisierte Templates in der `prompts.yaml`:
**Template-Struktur:**
* Explizite Variablen für jeden Stream (z.B. `{values_stream}`, `{risk_stream}`).
* **Pre-Initialization:** Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors).
* **Provider-spezifische Templates:** Separate Versionen für Ollama, Gemini und OpenRouter.
**Synthese-Strategien (Profil-gesteuert):**
* **FACT_WHAT/FACT_WHEN:** Nutzt `synthesis_pro` - Kombiniert Fakten, Biographie und Technik.
* **DECISION:** Nutzt `synthesis_pro` - Wägt Fakten gegen Werte ab, evaluiert Risiken.
* **EMPATHY:** Nutzt `synthesis_pro` - Fokus auf Biographie und Werte.
* **CODING:** Nutzt `tech_expert` - Spezialisiertes Modell für Code & Technik.
**Profil-Auflösung:**
Jede Strategie kann ein individuelles `llm_profile` definieren. Fehlt diese Angabe, wird `synthesis_pro` als Standard verwendet.
### 1.7 RAG Flow (Technisch - WP-25a)
Wenn der Intent nicht `INTERVIEW` ist, wird folgender Flow ausgeführt:
1. **Intent Detection:** Hybrid Router klassifiziert die Anfrage via `router_profile` (z.B. `compression_fast`).
2. **Multi-Stream Retrieval:**
* Parallele Abfragen in spezialisierten Streams via `DecisionEngine._execute_parallel_streams()`.
* Jeder Stream nutzt individuelle Filter, Edge-Boosts und Query-Templates.
3. **Pre-Synthesis Kompression (WP-25a):**
* Streams über `compression_threshold` werden via `compression_profile` verdichtet.
* Parallelisierung über `asyncio.gather()` für mehrere Streams gleichzeitig.
4. **Wissens-Synthese:**
* Strategie-spezifisches `llm_profile` (z.B. `tech_expert` für CODING) steuert die finale Antwortgenerierung.
* Fallback-Kaskade bei Fehlern (automatisch via LLMService).
3. **Context Formatting:**
* Stream-Ergebnisse werden in formatierte Kontext-Strings umgewandelt.
* **Ollama Context-Throttling:** Kontext wird auf `MAX_OLLAMA_CHARS` begrenzt (Standard: 10.000).
4. **Synthese:**
* `DecisionEngine._generate_final_answer()` kombiniert alle Streams.
* Template-basierte Prompt-Konstruktion mit Stream-Variablen.
5. **Response:**
* LLM-Antwort wird generiert (provider-spezifisch).
* **Sources:** Alle Treffer aus allen Streams werden dedupliziert und zurückgegeben.
---
## 2. LLM Service & Traffic Control (WP-20)
## 2. LLM Service & Traffic Control (WP-20 / WP-25)
Der `LLMService` (`app/services/llm_service.py`) fungiert als zentraler Hybrid-Client für OpenRouter, Google Gemini und Ollama. Er schützt das System vor Überlastung und verwaltet Quoten.
Der `LLMService` (`app/services/llm_service.py`, v3.4.2) fungiert als zentraler Hybrid-Client für OpenRouter, Google Gemini und Ollama. Er schützt das System vor Überlastung und verwaltet Quoten.
**WP-25 Integration:**
* **Lazy Initialization:** `DecisionEngine` wird erst bei Bedarf initialisiert (verhindert Circular Imports).
* **Ingest-Stability Patch:** Entfernung des <5-Zeichen Guards ermöglicht YES/NO Validierungen beim Vault-Import.
* **Empty Response Guard:** Sicherung gegen leere `choices` Arrays bei OpenRouter (verhindert JSON-Errors).
Mit Version 2.8.1 wurde die Architektur der Antwort-Generierung grundlegend gehärtet:
@@ -107,10 +224,27 @@ In v2.8 wurde ein intelligentes Fehler-Handling für Cloud-Provider implementier
---
## 4. Feedback Traceability
## 4. Feedback Traceability & Stream-Tracing (WP-25)
Unterstützt das geplante Self-Tuning (WP08).
Unterstützt das geplante Self-Tuning (WP08) und ermöglicht Stream-spezifische Optimierung.
1. **Query ID:** Generiert bei jedem `/query` Call eine `UUIDv4`.
2. **Logging:** Speichert einen Snapshot in `data/logs/query_snapshot.jsonl` (Input + Retrieved Context).
3. **Feedback:** Der `/feedback` Endpoint verknüpft das User-Rating (1-5) mit der `query_id`.
1. **Query ID:** Generiert bei jedem `/chat` Call eine `UUIDv4`.
2. **Stream-Tracing:** Jeder Treffer enthält `stream_origin` für Zuordnung zum Quell-Stream.
3. **Logging:** Speichert einen Snapshot in `data/logs/query_snapshot.jsonl` (Input + Retrieved Context + Intent).
4. **Feedback:** Der `/feedback` Endpoint verknüpft das User-Rating (1-5) mit der `query_id` und `stream_origin`.
## 5. Lifespan Management (WP-25)
Die FastAPI-Anwendung (`app/main.py`, v1.0.0) implementiert **Lifespan-Management** für sauberen Startup und Shutdown:
**Startup:**
* Integritäts-Check der WP-25 Konfiguration (`decision_engine.yaml`, `prompts.yaml`).
* Validierung kritischer Dateien vor dem Start.
**Shutdown:**
* Ressourcen-Cleanup (LLMService-Connections schließen).
* Graceful Shutdown für asynchrone Prozesse.
**Globale Fehlerbehandlung:**
* Fängt unerwartete Fehler in der Multi-Stream Kette ab.
* Strukturierte JSON-Responses bei Engine-Fehlern.
@@ -1,10 +1,10 @@
---
doc_type: technical_reference
audience: developer, admin
scope: configuration, env, registry, scoring, resilience, modularization
scope: configuration, env, registry, scoring, resilience, modularization, agentic_rag, moe, lazy_prompts
status: active
version: 2.9.1
context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen und die Edge Registry Struktur unter Berücksichtigung von WP-14."
version: 3.1.1
context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen, Edge Registry Struktur, WP-25 Multi-Stream RAG, WP-25a Mixture of Experts (MoE) und WP-25b Lazy-Prompt-Orchestration unter Berücksichtigung von WP-14."
---
# Konfigurations-Referenz
@@ -20,13 +20,15 @@ Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts. Seit der
| `QDRANT_URL` | `http://localhost:6333` | URL zur Vektor-DB API. |
| `QDRANT_API_KEY` | *(leer)* | Optionaler Key für Absicherung. |
| `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). |
| `MINDNET_PREFIX` | *(leer)* | **Alternative zu COLLECTION_PREFIX.** Falls gesetzt, wird dieser Wert verwendet. |
| `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). |
| `MINDNET_DISTANCE` | `Cosine` | Metrik für Vektor-Ähnlichkeit (`Cosine`, `Euclidean`, `Dot`). |
| `MINDNET_VECTOR_NAME` | `default` | **Neu (WP-14):** Basis-Vektorname für Named Vectors Support. |
| `NOTES_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Notes-Collection (Override). |
| `CHUNKS_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Chunks-Collection (Override). |
| `EDGES_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Edges-Collection (Override). |
| `MINDNET_VOCAB_PATH` | *(Pfad)* | **Neu (WP-22):** Absoluter Pfad zur `01_edge_vocabulary.md`. Definiert den Ort des Dictionarys. |
| `MINDNET_VAULT_ROOT` | `./vault` | Basis-Pfad für Datei-Operationen. |
| `MINDNET_VAULT_ROOT` | `./vault_master` | **Achtung:** Standard ist `./vault_master`, nicht `./vault`! Basis-Pfad für Datei-Operationen. |
| `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. |
| `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. |
| `MINDNET_DECISION_CONFIG` | `config/decision_engine.yaml` | Pfad zur Router & Intent Config. |
@@ -222,15 +224,16 @@ Die Datei muss eine Markdown-Tabelle enthalten, die vom Regex-Parser gelesen wir
---
## 5. Decision Engine (`decision_engine.yaml`)
## 5. Decision Engine (`decision_engine.yaml` v3.1.6)
Die Decision Engine fungiert als zentraler Orchestrator für die Intent-Erkennung und das dynamische Retrieval-Routing. Sie bestimmt, wie das System auf eine Nutzeranfrage reagiert, welche Informationstypen bevorzugt werden und wie der Wissensgraph für die spezifische Situation verformt wird.
Die Decision Engine fungiert als zentraler **Agentic Orchestrator** für die Intent-Erkennung und das dynamische Multi-Stream Retrieval-Routing (WP-25). Sie bestimmt, wie das System auf eine Nutzeranfrage reagiert, welche Wissens-Streams aktiviert werden und wie die Ergebnisse synthetisiert werden.
### 5.1 Intent Recognition: Dual-Path Routing
Das System nutzt ein zweistufiges Verfahren, um die Absicht des Nutzers zu identifizieren:
### 5.1 Intent Recognition: Hybrid-Routing (WP-25)
Das System nutzt einen **Hybrid-Modus** mit Keyword Fast-Path und LLM Slow-Path:
1. **Fast Path (Keyword Trigger):** Das System scannt die Anfrage nach definierten `trigger_keywords`. Wird ein Treffer gefunden, wird die entsprechende Strategie sofort ohne LLM-Einsatz gewählt.
2. **Slow Path (LLM Router):** Wenn kein Keyword matcht und `llm_fallback_enabled: true` gesetzt ist, analysiert ein LLM die Nachricht mittels Few-Shot Prompting.
1. **Fast Path (Keyword Trigger):** Das System scannt die Anfrage nach definierten `trigger_keywords`. Wird ein Treffer gefunden, wird die entsprechende Strategie sofort ohne LLM-Einsatz gewählt (z.B. "Soll ich" → `DECISION`).
2. **Type Keywords:** Prüft `detection_keywords` aus `types.yaml` für Interview-Modus (z.B. "Projekt" + "neu" → `INTERVIEW`).
3. **Slow Path (LLM Router):** Wenn kein Keyword matcht und `llm_fallback_enabled: true` gesetzt ist, analysiert ein LLM die Nachricht mittels Few-Shot Prompting (`intent_router_v1`).
#### LLM Router Konfiguration
Der Router nutzt den `llm_router_prompt`, um Anfragen in eine der fünf Kern-Strategien (`FACT`, `DECISION`, `EMPATHY`, `CODING`, `INTERVIEW`) zu klassifizieren.
@@ -242,36 +245,471 @@ Der Router nutzt den `llm_router_prompt`, um Anfragen in eine der fünf Kern-Str
---
### 5.2 Strategie-Mechaniken (Graph Shaping)
Jede Strategie definiert drei Hebel, um das Ergebnis des Retrievers zu beeinflussen:
### 5.2 Multi-Stream Konfiguration (WP-25)
* **`inject_types`:** Erzwingt die Einbindung bestimmter Notiz-Typen (z. B. `value` bei Entscheidungen), auch wenn diese semantisch eine geringere Ähnlichkeit aufweisen.
Seit WP-25 nutzt die Decision Engine eine **Stream-Library** mit spezialisierten Wissens-Streams:
**Stream-Library (`streams_library`):**
* **`values_stream`:** Identität, Ethik und Prinzipien (filter_types: `value`, `principle`, `belief`, `trait`, `boundary`, `need`, `motivation`)
* **`facts_stream`:** Operative Daten (filter_types: `project`, `decision`, `task`, `goal`, `event`, `state`)
* **`biography_stream`:** Persönliche Erfahrungen (filter_types: `experience`, `journal`, `profile`, `person`)
* **`risk_stream`:** Hindernisse und Gefahren (filter_types: `risk`, `obstacle`, `bias`)
* **`tech_stream`:** Technisches Wissen (filter_types: `concept`, `source`, `glossary`, `idea`, `insight`, `skill`, `habit`)
**Stream-Parameter:**
* **`query_template`:** Transformiert die ursprüngliche Anfrage für spezialisierte Suche (z.B. "Welche meiner Werte und Prinzipien betreffen: {query}")
* **`filter_types`:** Strikte Synchronisation mit `types.yaml` (v2.7.0)
* **`top_k`:** Anzahl der Treffer pro Stream (z.B. 5 für Values, 3 für Risk)
* **`edge_boosts`:** Individuelle Edge-Gewichtung pro Stream (z.B. `guides: 3.0` für Values Stream)
**Strategie-Komposition (`strategies`):**
Jede Strategie definiert, welche Streams aktiviert werden:
* **`use_streams`:** Liste der Stream-Keys, die parallel abgefragt werden (z.B. `["values_stream", "facts_stream", "risk_stream"]` für `DECISION`)
* **`prompt_template`:** Template-Key aus `prompts.yaml` für die Wissens-Synthese (z.B. `decision_synthesis_v1`)
* **`prepend_instruction`:** Optional: Zusätzliche Anweisung für das LLM (z.B. "Analysiere die Fakten vor dem Hintergrund meiner Werte")
* **`preferred_provider`:** Optional: Provider-Präferenz für diese Strategie (z.B. `gemini` für DECISION)
### 5.3 Strategie-Mechaniken (Graph Shaping)
Jede Strategie definiert mehrere Hebel, um das Ergebnis zu beeinflussen:
* **`use_streams`:** Aktiviert parallele Wissens-Streams (WP-25).
* **`edge_boosts`:** Erhöht die Gewichtung spezifischer Kanten-Typen in der Scoring-Formel. Dies ermöglicht es dem Graphen, die Textsuche situativ zu "überstimmen".
* **`prepend_instruction`:** Injiziert eine spezifische Systemanweisung in das LLM-Prompt, um den Antwortstil anzupassen (z. B. "Wäge Fakten gegen Werte ab").
---
### 5.3 Übersicht der Strategien
### 5.4 Übersicht der Strategien (WP-25)
| Strategie | Fokus | Bevorzugte Kanten (`edge_boosts`) | Injektionstypen |
| Strategie | Fokus | Aktive Streams | Bevorzugte Kanten (`edge_boosts`) |
| :--- | :--- | :--- | :--- |
| **FACT** | Wissensabfrage & Definitionen | `part_of` (2.0), `composed_of` (2.0), `similar_to` (1.5) | *(Keine)* |
| **DECISION** | Rat, Strategie & Abwägung | `blocks` (2.5), `solves` (2.0), `risk_of` (2.5) | `value`, `principle`, `goal`, `risk` |
| **EMPATHY** | Emotionale Resonanz | `based_on` (2.0), `experienced_in` (2.5), `related_to` (2.0) | `experience`, `belief`, `profile` |
| **CODING** | Programmierung & Syntax | `implemented_in` (3.0), `uses` (2.5), `depends_on` (2.0) | `snippet`, `reference`, `source` |
| **INTERVIEW** | Erfassung neuer Daten | *(Keine)* | *(Keine)* |
| **FACT_WHAT** | Wissensabfrage & Listen | `facts_stream`, `tech_stream`, `biography_stream` | `part_of` (2.0), `depends_on` (1.5), `implemented_in` (1.5) |
| **FACT_WHEN** | Zeitpunkte & Termine | `facts_stream`, `biography_stream`, `tech_stream` | `part_of` (2.0), `depends_on` (1.5) |
| **DECISION** | Rat, Strategie & Abwägung | `values_stream`, `facts_stream`, `risk_stream` | `blocks` (2.5), `impacts` (2.0), `risk_of` (2.5) |
| **EMPATHY** | Emotionale Resonanz | `biography_stream`, `values_stream` | `related_to` (1.5), `experienced_in` (2.0) |
| **CODING** | Programmierung & Syntax | `tech_stream`, `facts_stream` | `uses` (2.5), `implemented_in` (3.0) |
| **INTERVIEW** | Erfassung neuer Daten | *(Keine Streams)* | *(Keine)* |
---
### 5.4 Der Interview-Modus & Schemas
### 5.5 Der Interview-Modus & Schemas
Die Strategie `INTERVIEW` dient der strukturierten Datenerfassung.
* **Trigger:** Aktiviert durch Phrasen wie "neue notiz", "festhalten" oder "dokumentieren".
* **Trigger:** Aktiviert durch Phrasen wie "neue notiz", "festhalten" oder "dokumentieren" (Type Keywords aus `types.yaml`).
* **Schema-Logik:** Nutzt das `default`-Schema mit den Feldern `Titel`, `Thema/Inhalt` und `Tags`, sofern kein spezifisches Typ-Schema aus der `types.yaml` greift.
* **Dynamik:** In diesem Modus wird der Fokus vom Retrieval (Wissen finden) auf die Extraktion (Wissen speichern) verschoben.
* **Streams:** Keine Streams aktiviert (leere `use_streams` Liste).
> **Hinweis:** Da spezifische Schemas für Projekte oder Erfahrungen direkt in der `types.yaml` definiert werden, dient die `decision_engine.yaml` hier primär als Fallback für generische Datenaufnahmen.
### 5.6 Prompts-Konfiguration (`prompts.yaml` v3.2.2 - WP-25b)
Seit WP-25b nutzt MindNet eine **hierarchische Prompt-Struktur** mit Lazy-Loading. Prompts werden erst zur Laufzeit geladen, basierend auf dem exakt aktiven Modell.
**Hierarchische Template-Struktur:**
```yaml
decision_synthesis_v1:
# Level 1: Modell-spezifisch (höchste Priorität)
"google/gemini-2.0-flash-exp:free": |
WERTE & PRINZIPIEN (Identität):
{values_stream}
OPERATIVE FAKTEN (Realität):
{facts_stream}
RISIKO-RADAR (Konsequenzen):
{risk_stream}
ENTSCHEIDUNGSFRAGE:
{query}
Nutze deine hohe Reasoning-Kapazität für eine tiefe Synthese.
"meta-llama/llama-3.3-70b-instruct:free": |
Erstelle eine fundierte Synthese für die Frage: "{query}"
Nutze die Daten: {values_stream}, {facts_stream} und {risk_stream}.
Trenne klare Fakten von Erfahrungen. Bleibe strikt beim bereitgestellten Kontext.
# Level 2: Provider-Fallback (mittlere Priorität)
openrouter: |
WERTE & PRINZIPIEN (Identität):
{values_stream}
OPERATIVE FAKTEN (Realität):
{facts_stream}
RISIKO-RADAR (Konsequenzen):
{risk_stream}
ENTSCHEIDUNGSFRAGE:
{query}
ollama: |
WERTE & PRINZIPIEN (Identität):
{values_stream}
OPERATIVE FAKTEN (Realität):
{facts_stream}
RISIKO-RADAR (Konsequenzen):
{risk_stream}
ENTSCHEIDUNGSFRAGE:
{query}
# Level 3: Global Default (niedrigste Priorität)
default: |
Synthetisiere die folgenden Informationen für: {query}
{values_stream} | {facts_stream} | {risk_stream}
```
**Auflösungs-Logik:**
1. **Level 1:** Exakte Modell-ID (z.B. `google/gemini-2.0-flash-exp:free`)
2. **Level 2:** Provider-Fallback (z.B. `openrouter`, `ollama`, `gemini`)
3. **Level 3:** Global Default (`default` → `gemini` → `ollama` → `""`)
**Lazy-Loading:**
* Prompts werden erst zur Laufzeit geladen, wenn das aktive Modell bekannt ist
* **Parameter:** `prompt_key` und `variables` statt vorformatierter Strings
* **Vorteil:** Maximale Resilienz bei Modell-Fallbacks (Cloud → Local)
**Pre-Initialization:**
Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors bei unvollständigen Konfigurationen).
**PROMPT-TRACE Logging:**
Das System protokolliert die genutzte Auflösungs-Ebene:
* `🎯 [PROMPT-TRACE] Level 1 Match: Model-specific`
* `📡 [PROMPT-TRACE] Level 2 Match: Provider-fallback`
* `⚓ [PROMPT-TRACE] Level 3 Match: Global Default`
---
## 6. LLM Profile Registry (`llm_profiles.yaml` v1.3.0)
Seit WP-25a nutzt MindNet eine **Mixture of Experts (MoE)** Architektur mit profilbasierter Experten-Steuerung. Jede Systemaufgabe (Synthese, Ingestion-Validierung, Routing, Kompression) wird einem dedizierten Profil zugewiesen, das Modell, Provider und Parameter unabhängig von der globalen Konfiguration definiert.
### 6.1 Profil-Struktur
Jedes Profil definiert:
* **`provider`:** Cloud-Provider (`openrouter`, `gemini`, `ollama`)
* **`model`:** Spezifisches Modell (z.B. `mistralai/mistral-7b-instruct:free`)
* **`temperature`:** Kreativität/Determinismus (0.0 = deterministisch, 1.0 = kreativ)
* **`fallback_profile`:** Optional: Name des Fallback-Profils bei Fehlern
* **`dimensions`:** Optional: Für Embedding-Profile (z.B. 768 für nomic-embed-text)
**Beispiel:**
```yaml
synthesis_pro:
provider: "openrouter"
model: "gemini-1.5-mistralai/mistral-7b-instruct:free"
temperature: 0.7
fallback_profile: "synthesis_backup"
```
### 6.2 Verfügbare Experten-Profile
| Profil | Provider | Modell | Temperature | Fallback | Zweck |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **`synthesis_pro`** | openrouter | gemini-1.5-mistralai/mistral-7b-instruct:free | 0.7 | `synthesis_backup` | Hochwertige Synthese (Chat-Antworten) |
| **`synthesis_backup`** | openrouter | mistralai/mistral-large | 0.5 | `identity_safe` | Backup-Cloud-Experte (Resilienz) |
| **`tech_expert`** | openrouter | anthropic/claude-3.5-sonnet | 0.3 | `synthesis_pro` | Fachspezialist für Code & Technik |
| **`compression_fast`** | openrouter | mistralai/mistral-7b-instruct:free | 0.1 | `identity_safe` | Schnelle Kompression & Routing |
| **`ingest_extractor`** | openrouter | mistralai/mistral-7b-instruct:free | 0.2 | `synthesis_backup` | Extraktion komplexer Datenstrukturen |
| **`ingest_validator`** | openrouter | mistralai/mistral-7b-instruct:free | 0.0 | `compression_fast` | Binäre Prüfungen (YES/NO, deterministisch) |
| **`identity_safe`** | ollama | phi3:mini | 0.2 | *(kein Fallback)* | Lokaler Anker & Privacy (terminaler Endpunkt) |
| **`embedding_expert`** | ollama | nomic-embed-text | - | - | Embedding-Modell (dimensions: 768) |
### 6.3 Fallback-Kaskade (WP-25a)
Die Profile implementieren eine **rekursive Fallback-Kaskade**:
1. **Primäres Profil:** System versucht das angeforderte Profil (z.B. `synthesis_pro`)
2. **Fallback-Level 1:** Bei Fehler → `fallback_profile` (z.B. `synthesis_backup`)
3. **Fallback-Level 2:** Bei weiterem Fehler → nächster Fallback (z.B. `identity_safe`)
4. **Terminaler Endpunkt:** `identity_safe` hat keinen Fallback (lokales Modell als letzte Instanz)
**Schutzmechanismen:**
* **Zirkuläre Referenzen:** `visited_profiles`-Tracking verhindert Endlosschleifen
* **Background-Semaphore:** Parallele Tasks werden gedrosselt (konfigurierbar via `BACKGROUND_LIMIT`)
### 6.4 Integration in Decision Engine
Die `decision_engine.yaml` referenziert Profile über:
* **`router_profile`:** Profil für Intent-Erkennung (z.B. `compression_fast`)
* **`llm_profile`:** Profil für Strategie-spezifische Synthese (z.B. `tech_expert` für CODING)
* **`compression_profile`:** Profil für Stream-Kompression (z.B. `compression_fast`)
**Stream-Konfiguration:**
```yaml
values_stream:
llm_profile: "identity_safe" # Lokales Modell für Privacy
compression_profile: "identity_safe"
compression_threshold: 2500
```
### 6.5 Environment-Variablen
| Variable | Default | Beschreibung |
| :--- | :--- | :--- |
| `MINDNET_LLM_PROFILES_PATH` | `config/llm_profiles.yaml` | Pfad zur Profil-Registry |
**Hinweis:** Die `.env` Variablen `MINDNET_LLM_PROVIDER`, `MINDNET_LLM_MODEL` etc. dienen nur noch als Fallback, wenn kein Profil angegeben wird.
---
## 7. Konfigurations-Verbindungen & Datenfluss
Die vier zentralen Konfigurationsdateien (`types.yaml`, `decision_engine.yaml`, `llm_profiles.yaml`, `prompts.yaml`) arbeiten eng zusammen, um das agentische Multi-Stream RAG System zu steuern. Diese Sektion erklärt die Verbindungen und zeigt einen konkreten Praxisablauf.
### 7.1 Architektur-Übersicht
```mermaid
graph TB
subgraph "1. Typ-Definition (types.yaml)"
T1[Typ: value<br/>chunking_profile: structured_strict<br/>retriever_weight: 1.00]
T2[Typ: risk<br/>chunking_profile: sliding_short<br/>retriever_weight: 0.85]
T3[Typ: project<br/>chunking_profile: sliding_smart_edges<br/>retriever_weight: 0.97]
end
subgraph "2. Stream-Konfiguration (decision_engine.yaml)"
D1[values_stream<br/>filter_types: value, principle, belief...<br/>llm_profile: identity_safe<br/>compression_profile: identity_safe]
D2[risk_stream<br/>filter_types: risk, obstacle, bias<br/>llm_profile: synthesis_pro<br/>compression_profile: compression_fast]
D3[facts_stream<br/>filter_types: project, decision, task...<br/>llm_profile: synthesis_pro<br/>compression_profile: compression_fast]
end
subgraph "3. Strategie-Komposition (decision_engine.yaml)"
S1[DECISION Strategie<br/>use_streams: values_stream, facts_stream, risk_stream<br/>llm_profile: synthesis_pro<br/>prompt_template: decision_synthesis_v1]
end
subgraph "4. Experten-Profile (llm_profiles.yaml)"
P1[synthesis_pro<br/>provider: openrouter<br/>model: google/gemini-2.0-flash-exp:free<br/>temperature: 0.7<br/>fallback_profile: synthesis_backup]
P2[compression_fast<br/>provider: openrouter<br/>model: mistralai/mistral-7b-instruct:free<br/>temperature: 0.1<br/>fallback_profile: identity_safe]
P3[identity_safe<br/>provider: ollama<br/>model: phi3:mini<br/>temperature: 0.2<br/>fallback_profile: null]
end
subgraph "5. Prompt-Templates (prompts.yaml)"
PR1[decision_synthesis_v1<br/>Level 1: google/gemini-2.0-flash-exp:free<br/>Level 2: openrouter<br/>Level 3: default]
end
T1 -->|filter_types| D1
T2 -->|filter_types| D2
T3 -->|filter_types| D3
D1 -->|use_streams| S1
D2 -->|use_streams| S1
D3 -->|use_streams| S1
S1 -->|llm_profile| P1
D1 -->|llm_profile| P3
D2 -->|compression_profile| P2
D3 -->|compression_profile| P2
S1 -->|prompt_template| PR1
P1 -->|model lookup| PR1
style T1 fill:#e1f5ff
style T2 fill:#e1f5ff
style T3 fill:#e1f5ff
style D1 fill:#fff4e1
style D2 fill:#fff4e1
style D3 fill:#fff4e1
style S1 fill:#ffe1f5
style P1 fill:#e1ffe1
style P2 fill:#e1ffe1
style P3 fill:#e1ffe1
style PR1 fill:#f5e1ff
```
### 7.2 Verbindungs-Matrix
| Von | Zu | Verbindung | Beschreibung |
| :--- | :--- | :--- | :--- |
| **`types.yaml`** | **`decision_engine.yaml`** | `filter_types` | Streams filtern Notizen basierend auf Typen aus `types.yaml`. Die Liste `filter_types: ["value", "principle", "belief"]` muss exakt den Typ-Namen aus `types.yaml` entsprechen. |
| **`types.yaml`** | **`decision_engine.yaml`** | `detection_keywords` | Keywords aus `types.yaml` werden für den Interview-Modus verwendet (z.B. "Projekt" + "neu" → `INTERVIEW`). |
| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `router_profile` | Intent-Erkennung nutzt das Profil `compression_fast` für schnelle Klassifizierung. |
| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `llm_profile` (Stream) | Jeder Stream definiert sein eigenes Profil für Retrieval und Kompression (z.B. `identity_safe` für Privacy). |
| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `llm_profile` (Strategie) | Die finale Synthese nutzt das Strategie-Profil (z.B. `synthesis_pro` für DECISION). |
| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `compression_profile` | Überlange Streams werden via `compression_profile` verdichtet (z.B. `compression_fast`). |
| **`decision_engine.yaml`** | **`prompts.yaml`** | `prompt_template` | Strategien referenzieren Template-Keys (z.B. `decision_synthesis_v1`). |
| **`llm_profiles.yaml`** | **`prompts.yaml`** | Hierarchische Auflösung | Das aktive Modell aus dem Profil bestimmt, welcher Prompt-Level geladen wird (Model-ID → Provider → Default). |
| **`llm_profiles.yaml`** | **`llm_profiles.yaml`** | `fallback_profile` | Rekursive Fallback-Kaskade bei Fehlern (z.B. `synthesis_pro` → `synthesis_backup` → `identity_safe`). |
### 7.3 Praxisbeispiel: DECISION-Anfrage
**User-Anfrage:** `"Soll ich das neue Projekt starten?"`
#### Schritt 1: Intent-Erkennung
**Datei:** `decision_engine.yaml`
```yaml
settings:
router_profile: "compression_fast" # → llm_profiles.yaml
router_prompt_key: "intent_router_v1" # → prompts.yaml
```
**Ablauf:**
1. System prüft `trigger_keywords` in `DECISION` Strategie → findet `"soll ich"` → **Intent: DECISION**
2. Falls kein Keyword-Match: LLM-Router nutzt `compression_fast` Profil aus `llm_profiles.yaml`
3. Router lädt `intent_router_v1` aus `prompts.yaml` (hierarchisch basierend auf aktivem Modell)
#### Schritt 2: Stream-Aktivierung
**Datei:** `decision_engine.yaml`
```yaml
strategies:
DECISION:
use_streams: ["values_stream", "facts_stream", "risk_stream"]
llm_profile: "synthesis_pro" # → llm_profiles.yaml
prompt_template: "decision_synthesis_v1" # → prompts.yaml
```
**Ablauf:**
1. System aktiviert drei parallele Streams: `values_stream`, `facts_stream`, `risk_stream`
#### Schritt 3: Stream-Konfiguration & Typ-Filterung
**Datei:** `decision_engine.yaml` (Streams) + `types.yaml` (Typ-Definitionen)
```yaml
# decision_engine.yaml
values_stream:
filter_types: ["value", "principle", "belief", "trait", "boundary", "need", "motivation"]
llm_profile: "identity_safe" # → llm_profiles.yaml
compression_profile: "identity_safe" # → llm_profiles.yaml
query_template: "Welche meiner Werte und Prinzipien betreffen: {query}"
facts_stream:
filter_types: ["project", "decision", "task", "goal", "event", "state"]
llm_profile: "synthesis_pro" # → llm_profiles.yaml
compression_profile: "compression_fast" # → llm_profiles.yaml
query_template: "Status, Ressourcen und Fakten zu: {query}"
risk_stream:
filter_types: ["risk", "obstacle", "bias"]
llm_profile: "synthesis_pro" # → llm_profiles.yaml
compression_profile: "compression_fast" # → llm_profiles.yaml
query_template: "Gefahren, Hindernisse oder Risiken bei: {query}"
```
**Ablauf:**
1. **Values Stream:** Sucht in Qdrant nach Notizen mit `type IN ["value", "principle", "belief", ...]` (definiert in `types.yaml`)
2. **Facts Stream:** Sucht nach Notizen mit `type IN ["project", "decision", "task", ...]` (definiert in `types.yaml`)
3. **Risk Stream:** Sucht nach Notizen mit `type IN ["risk", "obstacle", "bias"]` (definiert in `types.yaml`)
#### Schritt 4: Profil-Auflösung & Modell-Auswahl
**Datei:** `llm_profiles.yaml`
```yaml
synthesis_pro:
provider: "openrouter"
model: "google/gemini-2.0-flash-exp:free"
temperature: 0.7
fallback_profile: "synthesis_backup" # → Rekursiver Fallback
compression_fast:
provider: "openrouter"
model: "mistralai/mistral-7b-instruct:free"
temperature: 0.1
fallback_profile: "identity_safe"
identity_safe:
provider: "ollama"
model: "phi3:mini"
temperature: 0.2
fallback_profile: null # Terminaler Endpunkt
```
**Ablauf:**
1. **Values Stream:** Nutzt `identity_safe` → Ollama/phi3:mini (lokal, Privacy)
2. **Facts Stream:** Nutzt `synthesis_pro` → OpenRouter/Gemini 2.0 (Cloud)
3. **Risk Stream:** Nutzt `synthesis_pro` → OpenRouter/Gemini 2.0 (Cloud)
4. **Kompression:** Falls Stream > `compression_threshold`, nutzt `compression_fast` → OpenRouter/Mistral 7B
#### Schritt 5: Prompt-Loading (Hierarchische Auflösung)
**Datei:** `prompts.yaml`
```yaml
decision_synthesis_v1:
# Level 1: Modell-spezifisch (höchste Priorität)
"google/gemini-2.0-flash-exp:free": |
Agiere als strategischer Partner für: {query}
WERTE: {values_stream} | FAKTEN: {facts_stream} | RISIKEN: {risk_stream}
Prüfe die Fakten gegen meine Werte. Zeige Zielkonflikte auf. Gib eine klare Empfehlung.
# Level 2: Provider-Fallback
openrouter: |
Strategische Multi-Stream Analyse für: {query}
Werte-Basis: {values_stream} | Fakten: {facts_stream} | Risiken: {risk_stream}
Bitte wäge ab und gib eine Empfehlung.
# Level 3: Global Default
default: "Prüfe {query} gegen Werte {values_stream} und Fakten {facts_stream}."
```
**Ablauf:**
1. System hat `synthesis_pro` Profil geladen → Modell: `google/gemini-2.0-flash-exp:free`
2. System sucht in `prompts.yaml` nach `decision_synthesis_v1`:
- **Level 1:** Findet exakten Match für `google/gemini-2.0-flash-exp:free` → **Verwendet diesen Prompt**
- Falls nicht gefunden: **Level 2** → `openrouter` Fallback
- Falls nicht gefunden: **Level 3** → `default` Fallback
3. Prompt wird mit Stream-Variablen formatiert: `{values_stream}`, `{facts_stream}`, `{risk_stream}`, `{query}`
#### Schritt 6: Finale Synthese
**Ablauf:**
1. System ruft LLM auf mit:
- **Profil:** `synthesis_pro` (OpenRouter/Gemini 2.0, Temperature 0.7)
- **Prompt:** Level-1 Template aus `prompts.yaml` (modell-spezifisch optimiert)
- **Variablen:** Formatierte Stream-Inhalte
2. Falls Fehler (z.B. Rate-Limit 429):
- **Fallback:** `synthesis_backup` (Llama 3.3)
- **Prompt:** Automatisch Level-2 (`openrouter`) oder Level-3 (`default`) geladen
3. Antwort wird an User zurückgegeben
### 7.4 Konfigurations-Synchronisation Checkliste
Beim Ändern einer Konfigurationsdatei müssen folgende Abhängigkeiten geprüft werden:
**✅ `types.yaml` ändern:**
- [ ] Prüfe, ob `filter_types` in `decision_engine.yaml` Streams noch gültig sind
- [ ] Prüfe, ob `detection_keywords` für Interview-Modus noch passen
- [ ] Prüfe, ob `chunking_profile` noch existiert (in `types.yaml` definiert)
**✅ `decision_engine.yaml` ändern:**
- [ ] Prüfe, ob alle `filter_types` in Streams existieren in `types.yaml`
- [ ] Prüfe, ob alle `llm_profile` / `compression_profile` existieren in `llm_profiles.yaml`
- [ ] Prüfe, ob alle `prompt_template` Keys existieren in `prompts.yaml`
**✅ `llm_profiles.yaml` ändern:**
- [ ] Prüfe, ob `fallback_profile` Referenzen zirkulär sind (Schutz: `visited_profiles`)
- [ ] Prüfe, ob alle referenzierten Profile existieren
- [ ] Prüfe, ob Modell-IDs mit `prompts.yaml` Level-1 Keys übereinstimmen (optional, aber empfohlen)
**✅ `prompts.yaml` ändern:**
- [ ] Prüfe, ob alle `prompt_template` Keys aus `decision_engine.yaml` existieren
- [ ] Prüfe, ob Modell-spezifische Keys (Level 1) mit `llm_profiles.yaml` Modell-IDs übereinstimmen
- [ ] Prüfe, ob alle Stream-Variablen (`{values_stream}`, `{facts_stream}`, etc.) initialisiert werden
### 7.5 Debugging-Tipps
**Problem:** Stream findet keine Notizen
- **Prüfung:** `filter_types` in Stream stimmt mit Typ-Namen in `types.yaml` überein? (Case-sensitive!)
- **Prüfung:** Existieren Notizen mit diesen Typen im Vault?
**Problem:** Falsches Modell wird verwendet
- **Prüfung:** `llm_profile` in Stream/Strategie existiert in `llm_profiles.yaml`?
- **Prüfung:** `fallback_profile` Kaskade führt zu unerwartetem Modell?
**Problem:** Prompt wird nicht gefunden
- **Prüfung:** `prompt_template` Key existiert in `prompts.yaml`?
- **Prüfung:** Hierarchische Auflösung (Level 1 → 2 → 3) funktioniert? (Logs: `[PROMPT-TRACE]`)
**Problem:** Kompression wird nicht ausgelöst
- **Prüfung:** `compression_threshold` in Stream-Konfiguration gesetzt?
- **Prüfung:** `compression_profile` existiert in `llm_profiles.yaml`?
---
Auszug aus der decision_engine.yaml
```yaml
@@ -3,7 +3,7 @@ doc_type: technical_reference
audience: developer, architect
scope: database, qdrant, schema
status: active
version: 2.8.0
version: 2.9.1
context: "Exakte Definition der Datenmodelle (Payloads) in Qdrant und Index-Anforderungen. Berücksichtigt WP-14 Modularisierung und WP-15b Multi-Hashes."
---
@@ -96,15 +96,19 @@ Es müssen Payload-Indizes für folgende Felder existieren:
## 4. Edge Payload (`mindnet_edges`)
Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Tracking.
Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Tracking. Seit v2.9.1 unterstützt das System **Section-basierte Links** (`[[Note#Section]]`), die in `target_id` und `target_section` aufgeteilt werden.
**JSON-Schema:**
```json
{
"edge_id": "string (keyword)", // Deterministischer Hash aus (src, dst, kind)
"edge_id": "string (keyword)", // Deterministischer Hash aus (src, dst, kind, variant)
// variant = target_section (erlaubt Multigraph für Sections)
"source_id": "string (keyword)", // Chunk-ID (Start)
"target_id": "string (keyword)", // Chunk-ID oder Note-Titel (bei Unresolved)
// WICHTIG: Enthält NUR den Note-Namen, KEINE Section-Info
"target_section": "string (keyword)", // Optional: Abschnitts-Name (z.B. "P3 – Disziplin")
// Wird aus [[Note#Section]] extrahiert
"kind": "string (keyword)", // Beziehungsart (z.B. 'depends_on')
"scope": "string (keyword)", // Immer 'chunk' (Legacy-Support: 'note')
"note_id": "string (keyword)", // Owner Note ID (Ursprung der Kante)
@@ -116,10 +120,18 @@ Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Track
}
```
**Section-Support (WP-15c):**
* Links wie `[[Note#Section]]` werden in `target_id="Note"` und `target_section="Section"` aufgeteilt.
* **Self-Links:** `[[#Section]]` wird zu `target_id="current_note_id"` und `target_section="Section"` aufgelöst.
* Die Edge-ID enthält die Section als `variant`, sodass mehrere Kanten zwischen denselben Knoten existieren können, wenn sie auf verschiedene Sections zeigen (Multigraph-Modus).
* Semantische Deduplizierung basiert auf `src->tgt:kind@sec` Key, um "Phantom-Knoten" zu vermeiden.
* **Metadaten-Persistenz:** `target_section`, `provenance` und `confidence` werden durchgängig im In-Memory Subgraph und Datenbank-Adapter erhalten.
**Erforderliche Indizes:**
Es müssen Payload-Indizes für folgende Felder existieren:
* `source_id`
* `target_id`
* `target_section` (neu: Keyword-Index für Section-basierte Filterung)
* `kind`
* `scope`
* `note_id`
@@ -3,7 +3,7 @@ doc_type: technical_reference
audience: developer, frontend_architect
scope: architecture, graph_viz, state_management
status: active
version: 2.7.0
version: 2.9.1
context: "Technische Dokumentation des modularen Streamlit-Frontends, der Graph-Engines und des Editors."
---
@@ -1,10 +1,10 @@
---
doc_type: technical_reference
audience: developer, devops
scope: backend, ingestion, smart_edges, edge_registry, modularization
scope: backend, ingestion, smart_edges, edge_registry, modularization, moe, lazy_prompts
status: active
version: 2.9.0
context: "Detaillierte technische Beschreibung der Import-Pipeline, Two-Pass-Workflow (WP-15b) und modularer Datenbank-Architektur (WP-14). Integriert Mistral-safe Parsing und Deep Fallback."
version: 2.14.0
context: "Detaillierte technische Beschreibung der Import-Pipeline, Two-Pass-Workflow (WP-15b), modularer Datenbank-Architektur (WP-14), WP-25a profilgesteuerte Validierung und WP-25b Lazy-Prompt-Orchestration. Integriert Mistral-safe Parsing und Deep Fallback."
---
# Ingestion Pipeline & Smart Processing
@@ -31,9 +31,10 @@ Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durc
4. **Edge Registry Initialisierung (WP-22):**
* Laden der Singleton-Instanz der `EdgeRegistry`.
* Validierung der Vokabular-Datei unter `MINDNET_VOCAB_PATH`.
5. **Config Resolution (WP-14):**
5. **Config Resolution (WP-14 / v2.13.12):**
* Bestimmung von `chunking_profile` und `retriever_weight` via zentraler `TypeRegistry`.
* **Priorität:** 1. Frontmatter (Override) -> 2. `types.yaml` (Type) -> 3. Global Default.
* **Registry-First Profiling:** Automatische Anwendung der korrekten Profile basierend auf dem Note-Typ (z.B. `value` nutzt automatisch `structured_smart_edges_strict`).
6. **LocalBatchCache & Summary Generation (WP-15b):**
* Erstellung von Kurz-Zusammenfassungen für jede Note.
* Speicherung im `batch_cache` als Referenzrahmen für die spätere Kantenvalidierung.
@@ -49,9 +50,16 @@ Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durc
* Bei Änderungen löscht `purge_artifacts()` via `app.core.ingestion.ingestion_db` alle alten Chunks und Edges der Note.
* Die Namensauflösung erfolgt nun über das modularisierte `database`-Paket.
10. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3).
11. **Smart Edge Allocation & Semantic Validation (WP-15b):**
11. **Smart Edge Allocation & Semantic Validation (WP-15b / WP-25a / WP-25b):**
* Der `SemanticAnalyzer` schlägt Kanten-Kandidaten vor.
* **Validierung:** Jeder Kandidat wird durch das LLM semantisch gegen das Ziel im **LocalBatchCache** geprüft.
* **Validierung (WP-25a/25b):** Jeder Kandidat wird durch das LLM semantisch gegen das Ziel im **LocalBatchCache** geprüft.
* **Profilgesteuerte Validierung:** Nutzt das MoE-Profil `ingest_validator` (Temperature 0.0 für maximale Determinismus).
* **Lazy-Prompt-Loading (WP-25b):** Nutzt `prompt_key="edge_validation"` mit `variables` statt vorformatierter Strings.
* **Hierarchische Resolution:** Level 1 (Modell-ID) → Level 2 (Provider) → Level 3 (Default)
* **Differenzierte Fehlerbehandlung (WP-25b):** Unterscheidung zwischen transienten (Netzwerk) und permanenten (Config) Fehlern:
* **Transiente Fehler:** Timeout, Connection, Network → Kante wird erlaubt (Datenverlust vermeiden)
* **Permanente Fehler:** Config, Validation, Invalid Response → Kante wird abgelehnt (Graph-Qualität schützen)
* **Fallback-Kaskade:** Bei Fehlern erfolgt automatischer Fallback via `fallback_profile` (z.B. `compression_fast` → `identity_safe`).
* **Traffic Control:** Nutzung der neutralen `clean_llm_text` Funktion zur Bereinigung von Steuerzeichen (<s>, [OUT]).
* **Deep Fallback (v2.11.14):** Erkennt "Silent Refusals". Liefert die Cloud keine verwertbaren Kanten, wird ein lokaler Fallback via Ollama erzwungen.
12. **Inline-Kanten finden:** Parsing von `[[rel:...]]` und Callouts.
@@ -59,14 +67,33 @@ Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durc
* Jede Kante wird via `EdgeRegistry` normalisiert (z.B. `basiert_auf` -> `based_on`).
* Unbekannte Typen werden in `unknown_edges.jsonl` protokolliert.
14. **Default- & Strukturkanten:** Anwendung der `edge_defaults` und Erzeugung von Systemkanten (`belongs_to`, `next`, `prev`).
15. **Embedding (Async):** Generierung der Vektoren via `nomic-embed-text` (768 Dimensionen).
15. **Embedding (Async - WP-25a):** Generierung der Vektoren via `embedding_expert` Profil aus `llm_profiles.yaml`.
* **Profil-Auflösung:** Das `EmbeddingsClient` lädt Modell und Dimensionen direkt aus dem Profil (z.B. `nomic-embed-text`, 768 Dimensionen).
* **Konsolidierung:** Entfernung der Embedding-Konfiguration aus der `.env` zugunsten zentraler Profil-Registry.
16. **Database Sync (WP-14):** Batch-Upsert aller Points in die Collections `{prefix}_chunks` und `{prefix}_edges` über die zentrale Infrastruktur.
---
## 2. Betrieb & CLI Befehle
### 2.1 Standard-Betrieb (Inkrementell)
### 2.1 API-Endpunkt: `/ingest/save` (Background Tasks)
Seit WP-14 nutzt der `/ingest/save` Endpunkt **Background Tasks** für non-blocking Ingestion:
**Workflow:**
1. **Request:** Frontend sendet Markdown an `/ingest/save`
2. **Sofortige Antwort:** API antwortet mit `status: "queued"` und `note_id: "pending"`
3. **Datei-Persistenz:** Markdown wird sofort auf Festplatte geschrieben
4. **Background Task:** Ingestion läuft asynchron im Hintergrund
- Chunking
- Embedding-Generierung
- Smart Edge Allocation (WP-15)
- Hybrid-Cloud-Analyse (WP-20)
5. **Vorteil:** Keine Timeouts bei großen Dateien oder langsamen LLM-Calls
**Hinweis:** Die tatsächliche `note_id` steht erst nach dem Parsing fest. Das Frontend sollte den `file_path` für Tracking nutzen.
### 2.2 CLI-Betrieb (Inkrementell)
Erkennt Änderungen via Multi-Hash.
```bash
@@ -109,19 +136,44 @@ Das Chunking ist profilbasiert und bezieht seine Konfiguration dynamisch aus der
| `sliding_smart_edges`| `sliding_window` | Max: 600, Target: 400 | Fließtexte (Projekte). |
| `structured_smart_edges` | `by_heading` | `strict: false` | Strukturierte Texte. |
### 3.2 Die `by_heading` Logik (v2.9 Hybrid)
### 3.2 Die `by_heading` Logik (v3.9.9 Atomic Section Logic)
Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften). Sie unterstützt ein "Safety Net" gegen zu große Chunks.
Die Strategie `by_heading` implementiert seit v3.9.9 das **"Pack-and-Carry-Over"** Verfahren (Regel 1-3), um Sektions-Überschriften und deren Inhalte atomar in Chunks zu halten.
* **Split Level:** Definiert die Tiefe (z.B. `2` = H1 & H2 triggern Split).
* **Modus "Strict" (`strict_heading_split: true`):**
* Jede Überschrift (`<= split_level`) erzwingt einen neuen Chunk.
* *Merge-Check:* Wenn der vorherige Chunk leer war (nur Überschriften), wird gemergt.
* *Safety Net:* Wird ein Abschnitt zu lang (> `max` Token), wird auch ohne Überschrift getrennt.
* **Modus "Soft" (`strict_heading_split: false`):**
* **Hierarchie-Check:** Überschriften *oberhalb* des Split-Levels erzwingen **immer** einen Split.
* **Füll-Logik:** Überschriften *auf* dem Split-Level lösen nur dann einen neuen Chunk aus, wenn der aktuelle Chunk die `target`-Größe erreicht hat.
* *Safety Net:* Auch hier greift das `max` Token Limit.
**Kernprinzipien:**
* **Atomic Section Logic:** Überschriften und deren Inhalte werden als atomare Einheiten behandelt und nicht über Chunk-Grenzen hinweg getrennt.
* **H1-Context Preservation:** Der Dokumenttitel (H1) wird zuverlässig als Breadcrumb in das Embedding-Fenster (`window`) aller Chunks injiziert.
* **Signature Alignment:** Parameter-Synchronisierung zwischen Orchestrator und Strategien (`context_prefix` statt `doc_title`).
**Split Level:** Definiert die Tiefe (z.B. `2` = H1 & H2 triggern Split).
**Modus "Strict" (`strict_heading_split: true`):**
* Jede Überschrift (`<= split_level`) erzwingt einen neuen Chunk.
* *Merge-Check:* Wenn der vorherige Chunk leer war (nur Überschriften), wird gemergt.
* *Safety Net:* Wird ein Abschnitt zu lang (> `max` Token), wird auch ohne Überschrift getrennt.
**Modus "Soft" (`strict_heading_split: false`):**
* **Hierarchie-Check:** Überschriften *oberhalb* des Split-Levels erzwingen **immer** einen Split.
* **Füll-Logik:** Überschriften *auf* dem Split-Level lösen nur dann einen neuen Chunk aus, wenn der aktuelle Chunk die `target`-Größe erreicht hat.
* **Pack-and-Carry-Over:** Wenn ein Abschnitt zu groß ist, wird er intelligent zerlegt, wobei der Rest (mit Überschrift) zurück in die Queue gelegt wird.
* *Safety Net:* Auch hier greift das `max` Token Limit.
### 3.3 Registry-First Profiling (v2.13.12)
Seit v2.13.12 nutzt der `IngestionService` die korrekte Hierarchie zur Ermittlung des Chunking-Profils:
**Priorität:**
1. **Frontmatter** (Override) - Explizite `chunking_profile` Angabe
2. **`types.yaml` Typ-Config** - Profil basierend auf `type`
3. **Global Defaults** - Fallback auf `sliding_standard`
**Wichtig:** Ein Hard-Fallback auf `sliding_standard` erfolgt nur noch, wenn keine Konfiguration existiert. Dies stellt sicher, dass Note-Typen wie `value` automatisch das korrekte Profil (z.B. `structured_smart_edges_strict`) erhalten.
### 3.4 Deterministic Hashing (v2.13.12)
Der `full`-Hash inkludiert nun alle strategischen Parameter (z.B. `split_level`, `strict_heading_split`), sodass Konfigurationsänderungen im Frontmatter zwingend einen Re-Import auslösen.
**Impact:** Änderungen an Chunking-Parametern werden zuverlässig erkannt, auch wenn der Text unverändert bleibt.
---
@@ -146,4 +198,6 @@ Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere
**2. Mistral-safe Parsing:** Automatisierte Bereinigung von LLM-Antworten in `ingestion_validation.py`. Stellt sicher, dass semantische Entscheidungen ("YES"/"NO") nicht durch technische Header verfälscht werden.
**3. Profilgesteuerte Validierung (WP-25a):** Die semantische Kanten-Validierung erfolgt zwingend über das MoE-Profil `ingest_validator` (Temperature 0.0 für Determinismus). Dies gewährleistet konsistente binäre Entscheidungen (YES/NO) unabhängig von der globalen Provider-Konfiguration.
**3. Purge Integrity:** Validierung, dass vor jedem Upsert alle assoziierten Artefakte in den Collections `{prefix}_chunks` und `{prefix}_edges` gelöscht wurden, um Daten-Duplikate zu vermeiden.
@@ -3,22 +3,29 @@ doc_type: technical_reference
audience: developer, data_scientist
scope: backend, retrieval, scoring, modularization
status: active
version: 2.9.0
context: "Detaillierte Dokumentation der Scoring-Algorithmen, inklusive WP-22 Lifecycle-Modifier, Intent-Boosting und WP-14 Modularisierung."
version: 2.9.1
context: "Detaillierte Dokumentation der Scoring-Algorithmen, inklusive WP-22 Lifecycle-Modifier, Intent-Boosting, WP-15c Diversity Engine und WP-14 Modularisierung."
---
# Retrieval & Scoring Algorithmen
Der Retriever unterstützt **Semantic Search** und **Hybrid Search**. Seit v2.4 nutzt Mindnet ein gewichtetes Scoring-Modell, das Semantik, Graphentheorie und Metadaten kombiniert. Mit Version 2.7 (WP-22) wurde dieses Modell um **Lifecycle-Faktoren** und **Intent-Boosting** erweitert sowie die Architektur modularisiert (WP-14).
## 1. Scoring Formel (v2.7.0)
## 1. Scoring Formel (WP-15c / v1.0.3)
Der Gesamtscore eines Treffers berechnet sich als gewichtete Summe. Alle Gewichte ($W$) und Modifier ($M$) sind in `retriever.yaml` und `decision_engine.yaml` konfigurierbar.
Seit WP-15c nutzt Mindnet eine **hybride Multiplikations-Formel** für präziseres Scoring. Alle Gewichte ($W$) und Modifier ($M$) sind in `retriever.yaml` und `decision_engine.yaml` konfigurierbar.
$$
TotalScore = (W_{sem} \cdot S_{sem} \cdot W_{type} \cdot M_{status}) + (W_{edge} \cdot B_{edge}) + (W_{cent} \cdot B_{cent}) + B_{intent}
Final = (Semantic \cdot StatusMult) \cdot (1 + TypeBoost + EdgeBonus + CentBonus)
$$
**Komponenten:**
* **Base Score:** `Semantic * StatusMult` (Lifecycle-Filter)
* **Boosts:** `TypeBoost + EdgeBonus + CentBonus` (additiv, dann multiplikativ auf Base)
* **Graph Boost Factor:** Intent-spezifische Verstärkung (1.5x bei aktivem Intent)
**Vorteil:** Status wirkt als Multiplikator auf die Basis-Relevanz, Graph-Boni werden proportional verstärkt.
### Die Komponenten (Klassisch v2.4)
**1. Semantic Score ($S_{sem}$):**
@@ -43,13 +50,15 @@ $$
### Die WP-22 Erweiterungen (v2.7.0)
**5. Status Modifier ($M_{status}$):**
**5. Status Modifier ($M_{status}$) - Status-Gatekeeper:**
* **Herkunft:** Feld `status` aus dem Frontmatter (verarbeitet in `retriever_scoring.get_status_multiplier`).
* **Zweck:** Bestraft unfertiges Wissen (Drafts) oder bevorzugt stabiles Wissen.
* **Werte (Auftrag WP-22):** * `stable`: **1.2** (Belohnung für verifiziertes Wissen).
* `active`: **1.0** (Standard-Gewichtung).
* `draft`: **0.5** (Malus für unfertige Fragmente).
* `system`: Exkludiert (siehe Ingestion Lifecycle Filter).
* **Zweck:** Wirkt als **Multiplikator** auf die Basis-Semantik. Bestraft unfertiges Wissen (Drafts) oder bevorzugt stabiles Wissen.
* **Werte (WP-15c):**
* `stable`: **1.2** (Belohnung für verifiziertes Wissen)
* `active`: **1.0** (Standard-Gewichtung)
* `draft`: **0.5** (Malus für unfertige Fragmente)
* `system`: Exkludiert (siehe Ingestion Lifecycle Filter)
* **Impact:** Der Status wirkt direkt auf die semantische Ähnlichkeit, bevor Graph-Boni berechnet werden.
**6. Intent Boost ($B_{intent}$):**
* **Herkunft:** Dynamische Injektion durch die Decision Engine basierend auf der Nutzerfrage.
@@ -70,16 +79,25 @@ Seit v2.9 ist die Retrieval-Engine im spezialisierten Paket `app.core.retrieval`
* Diese delegiert an `app.core.graph.graph_subgraph`, um direkte Nachbarn aus der `_edges` Collection zu laden.
* Konstruktion eines in-memory Graphen zur Berechnung topologischer Boni.
**Phase 3: Re-Ranking (Modular)**
**Phase 3: Graph-Intelligenz & Super-Edge Aggregation (WP-15c)**
* **Super-Edge Aggregation:** Parallele Kanten zwischen zwei Notizen (z.B. auf verschiedene Sections) werden mathematisch zu einer "Super-Edge" aggregiert:
* Primäre Kante zählt voll (höchstes Gewicht)
* Weitere Kanten werden mit Dämpfungsfaktor **0.1** gewichtet
* Verhindert Score-Explosionen durch multiple Links
* **Provenance Weighting:** Kanten werden nach Provenance gewichtet (`explicit`=1.0, `smart`=0.9, `rule`=0.7)
* **Intent Boost:** Dynamische Multiplikatoren für spezifische Kanten-Typen (z.B. `caused_by` bei "Warum"-Fragen)
**Phase 4: Re-Ranking & Diversity Pooling (WP-15c)**
* Der Orchestrator übergibt den Graphen und die Seeds an die `ScoringEngine` (`retriever_scoring.py`).
* Berechnung der finalen Scores unter Berücksichtigung von $B_{edge}$, $B_{cent}$ sowie der Lifecycle- und Intent-Modifier.
* **Note-Level Diversity Pooling:** Pro `note_id` wird nur der relevanteste Treffer behalten (verhindert "Note-Flooding").
* Sortierung absteigend nach `TotalScore` und Limitierung auf die angeforderten Top-Resultate.
---
## 3. Explanation Layer (WP-22 Update)
## 3. Explanation Layer (WP-15c)
Bei `explain=True` generiert das System eine detaillierte Begründung inklusive Provenienz-Informationen.
Bei `explain=True` generiert das System eine detaillierte Begründung inklusive Provenienz-Informationen. Der Explanation Layer liefert detaillierte Begründungen für jeden Bonus (z.B. Sektions-Links oder Hub-Zentralität), was die Transparenz massiv erhöht.
**Erweiterte JSON-Struktur:**
+130 -14
View File
@@ -1,10 +1,10 @@
---
doc_type: operations_manual
audience: admin, devops
scope: deployment, maintenance, backup, edge_registry
scope: deployment, maintenance, backup, edge_registry, moe, lazy_prompts
status: active
version: 2.7.0
context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v2.7."
version: 3.1.1
context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v3.1.1 inklusive WP-25a Mixture of Experts (MoE) und WP-25b Lazy-Prompt-Orchestration Konfiguration."
---
# Admin Operations Guide
@@ -46,7 +46,7 @@ Um Abstürze der Vektordatenbank bei einer hohen Anzahl an Collections (z. B. du
Hintergrund: Qdrant öffnet für jedes Segment einer Collection mehrere Dateien. Ohne diese Erhöhung führt das Standard-Linux-Limit (1024) zum Absturz mit dem Fehler os error 24 (Too many open files).
### 1.3 Ollama (Modelle)
**Wichtig:** Seit v2.4 ist `nomic-embed-text` Pflicht für Embeddings.
**Wichtig:** Seit v2.4 ist `nomic-embed-text` Pflicht für Embeddings. Seit WP-25a wird die Modell-Konfiguration zentral über `llm_profiles.yaml` gesteuert.
```bash
# Modelle laden
@@ -57,6 +57,14 @@ ollama pull nomic-embed-text
curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}'
```
**WP-25a: LLM-Profil-Konfiguration**
Die LLM-Steuerung erfolgt nun primär über `config/llm_profiles.yaml` statt ENV-Variablen:
* **Zentrale Registry:** Alle Experten-Profile (Synthese, Validierung, Kompression) sind in einer Datei definiert
* **Fallback-Kaskade:** Automatische Resilienz bei Provider-Fehlern
* **ENV-Variablen:** `MINDNET_LLM_PROVIDER`, `MINDNET_LLM_MODEL` etc. dienen nur noch als Fallback
Siehe [Konfigurations-Referenz](../03_Technical_References/03_tech_configuration.md#6-llm-profile-registry-llm_profilesyaml-v130) für Details.
---
## 2. Deployment (Systemd Services)
@@ -131,30 +139,131 @@ Administratoren sollten regelmäßig das Log für unbekannte Kanten-Typen prüfe
### 3.3 Troubleshooting Guide
Dieser Abschnitt hilft bei häufigen Problemen und deren Lösung.
#### Allgemeine Diagnose-Schritte
Bevor du spezifische Fehler behebst, führe diese Checks durch:
1. **Service-Status prüfen:**
```bash
systemctl status mindnet-prod
systemctl status mindnet-ui-prod
docker ps | grep qdrant
```
2. **Logs analysieren:**
```bash
journalctl -u mindnet-prod -n 50 --no-pager
journalctl -u mindnet-ui-prod -n 50 --no-pager
docker logs qdrant --tail 50
```
3. **API-Verfügbarkeit testen:**
```bash
curl http://localhost:8001/health
curl http://localhost:8001/query -X POST -H "Content-Type: application/json" -d '{"query": "test", "top_k": 1}'
```
#### Häufige Fehler & Lösungen
**Fehler: "Registry Initialization Failure" (Neu in v2.7)**
* **Symptom:** API startet, aber Kanten werden nicht gewichtet oder Fehlermeldung im Log.
* **Lösung:** Prüfen Sie `MINDNET_VOCAB_PATH` in der `.env`. Der Pfad muss absolut sein und auf eine existierende Markdown-Tabelle zeigen.
* **Diagnose:** Prüfe die Logs auf `EdgeRegistry`-Fehler.
* **Lösung:**
1. Prüfe `MINDNET_VOCAB_PATH` in der `.env`. Der Pfad muss absolut sein.
2. Stelle sicher, dass die Datei `01_edge_vocabulary.md` existiert und eine gültige Markdown-Tabelle enthält.
3. Prüfe Dateiberechtigungen: `ls -l $MINDNET_VOCAB_PATH`
**Fehler: "ModuleNotFoundError: No module named 'st_cytoscape'"**
* Ursache: Alte Dependencies oder falsches Paket installiert.
* Lösung: Environment aktualisieren.
* **Ursache:** Alte Dependencies oder falsches Paket installiert.
* **Lösung:** Environment aktualisieren.
```bash
source .venv/bin/activate
pip uninstall streamlit-cytoscapejs
pip install st-cytoscape
pip install -r requirements.txt # Vollständige Synchronisation
```
**Fehler: "Vector dimension error: expected 768, got 384"**
* Ursache: Alte DB (v2.2), neues Modell (v2.4).
* Lösung: **Full Reset** (siehe Kap. 4.2).
* **Ursache:** Alte DB (v2.2), neues Modell (v2.4) oder falsches Embedding-Modell.
* **Diagnose:** Prüfe die Collection-Konfiguration in Qdrant.
* **Lösung:** **Full Reset** (siehe Kap. 4.2) oder Collection neu erstellen:
```bash
python3 -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes
python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply --force
```
**Fehler: Import sehr langsam**
* Ursache: Smart Edges sind aktiv und analysieren jeden Chunk.
* Lösung: `MINDNET_LLM_BACKGROUND_LIMIT` prüfen oder Feature in `types.yaml` deaktivieren.
* **Ursache:** Smart Edges sind aktiv und analysieren jeden Chunk mit LLM-Calls.
* **Diagnose:** Prüfe `MINDNET_LLM_BACKGROUND_LIMIT` und LLM-Provider-Status.
* **Lösung:**
1. Erhöhe `MINDNET_LLM_BACKGROUND_LIMIT` in `.env` (Standard: 2)
2. Oder deaktiviere Smart Edges temporär in `types.yaml` für bestimmte Typen
3. Prüfe, ob Ollama/Cloud-Provider erreichbar ist
**Fehler: UI "Read timed out"**
* Ursache: Backend braucht für Smart Edges länger als 60s.
* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env` setzen (oder im Systemd Service).
* **Ursache:** Backend braucht für Smart Edges länger als das Timeout-Limit.
* **Diagnose:** Prüfe Backend-Logs auf langsame LLM-Calls.
* **Lösung:**
1. Erhöhe `MINDNET_API_TIMEOUT=300.0` in `.env` (oder im Systemd Service)
2. Prüfe `MINDNET_LLM_TIMEOUT` für einzelne LLM-Requests
3. Erwäge, Smart Edges für große Imports zu deaktivieren
**Fehler: "Qdrant connection refused"**
* **Ursache:** Qdrant-Container läuft nicht oder falsche URL.
* **Lösung:**
```bash
docker ps | grep qdrant # Prüfe Container-Status
docker start qdrant # Starte Container falls gestoppt
docker logs qdrant # Prüfe Container-Logs
# Prüfe QDRANT_URL in .env
```
**Fehler: "Ollama model not found"**
* **Ursache:** Modell nicht geladen oder falscher Modellname.
* **Lösung:**
```bash
ollama list # Zeige geladene Modelle
ollama pull phi3:mini # Lade fehlendes Modell
ollama pull nomic-embed-text
# Prüfe MINDNET_LLM_MODEL und MINDNET_EMBEDDING_MODEL in .env
```
**Fehler: "Too many open files" (Qdrant)**
* **Ursache:** System-Limit für offene Dateien zu niedrig (besonders bei vielen Collections).
* **Lösung:** Erhöhe `ulimits` im Docker-Compose (siehe Kap. 1.2) oder systemweit:
```bash
# Temporär
ulimit -n 65535
# Permanently: /etc/security/limits.conf
```
**Fehler: "Unknown edge type" in Logs**
* **Ursache:** Neue Kanten-Typen im Vault, die nicht in `edge_vocabulary.md` definiert sind.
* **Diagnose:** Prüfe `data/logs/unknown_edges.jsonl`.
* **Lösung:**
1. Füge fehlende Typen als Aliase in `01_edge_vocabulary.md` hinzu
2. Oder verwende kanonische Typen aus der Registry
#### Performance-Optimierung
**Problem: Langsame Chat-Antworten**
* Prüfe LLM-Provider (Cloud vs. lokal)
* Reduziere `top_k` in Query-Requests
* Prüfe Qdrant-Performance (Anzahl Collections, Index-Größe)
**Problem: Hoher Speicherverbrauch**
* Reduziere `MINDNET_LLM_BACKGROUND_LIMIT`
* Prüfe Qdrant-Speicherverbrauch: `docker stats qdrant`
* Erwäge, alte Collections zu archivieren
#### Weitere Hilfe
Für detaillierte Informationen zu:
- **Server-Betrieb:** Siehe [Server Operations Manual](04_server_operation_manual.md)
- **Entwicklung:** Siehe [Developer Guide](../05_Development/05_developer_guide.md#10-troubleshooting--one-liners)
- **Konfiguration:** Siehe [Configuration Reference](../03_Technical_References/03_tech_configuration.md)
---
@@ -178,4 +287,11 @@ python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
# 2. Neu importieren (Force Hash recalculation)
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
```
```
**Wichtig (v2.9.1 Migration):**
Nach dem Update auf v2.9.1 (Section-basierte Links, Multigraph-Support) ist ein vollständiger Re-Import erforderlich, um "Phantom-Knoten" zu beheben und die neue Edge-Struktur zu konsolidieren:
```bash
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
```
Dies stellt sicher, dass alle bestehenden Links korrekt in `target_id` und `target_section` aufgeteilt werden.
+474
View File
@@ -0,0 +1,474 @@
---
doc_type: operations_manual
audience: devops, deployment_engineer
scope: deployment, ci_cd, rollout, versioning
status: active
version: 2.9.1
context: "Vollständiger Deployment-Guide für Mindnet: CI/CD, Rollout-Strategien, Versionierung und Rollback."
---
# Deployment Guide
Dieses Dokument beschreibt die Deployment-Prozesse, CI/CD-Pipelines und Rollout-Strategien für Mindnet.
## 1. Deployment-Architektur
Mindnet läuft in einer **Multi-Environment-Architektur**:
| Environment | Ports | Zweck | User |
| :--- | :--- | :--- | :--- |
| **Production** | 8001 (API), 8501 (UI) | Live-System | `llmadmin` |
| **Development** | 8002 (API), 8502 (UI) | Test & Entwicklung | `llmadmin` |
**Wichtig:** Beide Environments teilen sich die gleiche Qdrant-Instanz, nutzen aber unterschiedliche Collection-Prefixes.
---
## 2. Deployment-Methoden
### 2.1 Automatisches Deployment (CI/CD)
**Tool:** Gitea Actions (`.gitea/workflows/deploy.yml`)
**Trigger:** Push auf `main` Branch
**Prozess:**
1. **Checkout:** Code wird ausgecheckt
2. **Stop API:** Graceful Stop des API-Services
3. **Deploy:** Rsync der whitelisted Verzeichnisse
4. **Dependencies:** Python venv & requirements aktualisieren
5. **Restart:** API-Service neu starten
**Deployierte Verzeichnisse:**
- `app/` - Backend-Code
- `scripts/` - Admin-Tools
- `config/` - Konfigurationsdateien
- `tests/` - Test-Suite
- `requirements.txt` - Dependencies
**Ausgeschlossen:**
- `.env*` - Umgebungsvariablen (bleiben auf Server)
- `.venv` - Virtuelle Umgebung (wird neu erstellt)
- `vault/` - Content (bleibt auf Server)
### 2.2 Manuelles Deployment
**Für:** Hotfixes, manuelle Rollouts, Debugging
**Prozess:**
```bash
# 1. Auf Server einloggen
ssh llmadmin@llm-node
# 2. In Produktions-Verzeichnis wechseln
cd ~/mindnet
# 3. Code aktualisieren
git fetch origin
git checkout main
git pull origin main
# 4. Dependencies aktualisieren
source .venv/bin/activate
pip install -r requirements.txt
# 5. Services neu starten
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod
# 6. Status prüfen
sudo systemctl status mindnet-prod
sudo systemctl status mindnet-ui-prod
```
---
## 3. Systemd Services
### 3.1 Backend Service (API)
**Datei:** `/etc/systemd/system/mindnet-prod.service`
```ini
[Unit]
Description=Mindnet API Prod (8001)
After=network.target
[Service]
User=llmadmin
Group=llmadmin
WorkingDirectory=/home/llmadmin/mindnet
ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env
Restart=always
RestartSec=5
Environment="MINDNET_VOCAB_PATH=/home/llmadmin/mindnet/vault/_system/dictionary/edge_vocabulary.md"
[Install]
WantedBy=multi-user.target
```
**Wichtig:**
- `--env-file .env` lädt Umgebungsvariablen
- `MINDNET_VOCAB_PATH` muss absolut sein (für Edge Registry)
### 3.2 Frontend Service (UI)
**Datei:** `/etc/systemd/system/mindnet-ui-prod.service`
```ini
[Unit]
Description=Mindnet UI Prod (8501)
After=mindnet-prod.service
[Service]
User=llmadmin
Group=llmadmin
WorkingDirectory=/home/llmadmin/mindnet
Environment="MINDNET_API_URL=http://localhost:8001"
Environment="MINDNET_API_TIMEOUT=300"
Environment="STREAMLIT_SERVER_PORT=8501"
Environment="STREAMLIT_SERVER_ADDRESS=0.0.0.0"
Environment="STREAMLIT_SERVER_HEADLESS=true"
ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
```
### 3.3 Service-Management
**Befehle:**
```bash
# Status prüfen
sudo systemctl status mindnet-prod
sudo systemctl status mindnet-ui-prod
# Starten
sudo systemctl start mindnet-prod
sudo systemctl start mindnet-ui-prod
# Stoppen
sudo systemctl stop mindnet-prod
sudo systemctl stop mindnet-ui-prod
# Neustart
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod
# Logs anzeigen
sudo journalctl -u mindnet-prod -f
sudo journalctl -u mindnet-ui-prod -f
```
---
## 4. Rollout-Strategien
### 4.1 Blue-Green Deployment (Empfohlen)
**Konzept:** Zwei identische Environments, Switch zwischen ihnen.
**Aktuell:** Prod/Dev als Blue-Green Setup
**Vorgehen:**
1. Deploy auf Dev (Port 8002/8502)
2. Tests auf Dev durchführen
3. Wenn erfolgreich: Deploy auf Prod (Port 8001/8501)
4. Switch erfolgt durch Service-Restart
**Vorteile:**
- Schneller Rollback (alte Version läuft noch)
- Keine Downtime
- Test vor Produktion
### 4.2 Canary Deployment (Zukünftig)
**Konzept:** Schrittweise Rollout an einen Teil der Nutzer.
**Umsetzung:**
- Load Balancer mit Traffic-Splitting
- Monitoring der Fehlerrate
- Automatischer Rollback bei Fehlern
**Status:** Noch nicht implementiert (Single-User-Szenario)
---
## 5. Versionierung & Releases
### 5.1 Version-Schema
**Format:** `v2.9.1`
- **Major (2):** Breaking Changes
- **Minor (9):** Neue Features, Backward Compatible
- **Patch (1):** Bugfixes, kleine Verbesserungen
### 5.2 Release-Prozess
**1. Feature-Entwicklung:**
```bash
git checkout -b feature/neue-funktion
# ... Entwicklung ...
git push origin feature/neue-funktion
```
**2. Testing:**
- Unit Tests
- Integration Tests
- Smoke Tests auf Dev
**3. Merge:**
```bash
# Pull Request in Gitea
# Review & Merge nach main
```
**4. Deployment:**
- Automatisch via CI/CD (bei Push auf main)
- Oder manuell (siehe 2.2)
**5. Tagging (Optional):**
```bash
git tag -a v2.9.2 -m "Release v2.9.2: Neue Funktion X"
git push origin v2.9.2
```
---
## 6. Rollback-Strategien
### 6.1 Code-Rollback
**Methode 1: Git Revert**
```bash
cd ~/mindnet
git log --oneline -10 # Finde letzten guten Commit
git checkout <commit-hash>
sudo systemctl restart mindnet-prod
```
**Methode 2: Git Reset (Vorsicht!)**
```bash
cd ~/mindnet
git reset --hard <commit-hash>
sudo systemctl restart mindnet-prod
```
### 6.2 Datenbank-Rollback
**Problem:** Code-Rollback hilft nicht bei Schema-Änderungen.
**Lösung:**
- **Qdrant-Snapshots:** Regelmäßige Backups (siehe [Server Operations Manual](04_server_operation_manual.md))
- **Collection-Versionierung:** Separate Collections pro Version (nicht empfohlen)
**Vorgehen bei Schema-Änderung:**
1. Snapshot vor Deployment erstellen
2. Deployment durchführen
3. Bei Problemen: Snapshot wiederherstellen
---
## 7. Pre-Deployment Checkliste
Vor jedem Deployment sollten folgende Punkte geprüft werden:
- [ ] **Code-Qualität:**
- [ ] Unit Tests bestehen
- [ ] Integration Tests bestehen
- [ ] Linting bestanden
- [ ] **Dependencies:**
- [ ] `requirements.txt` aktualisiert
- [ ] Neue Dependencies dokumentiert
- [ ] Breaking Changes in Dependencies geprüft
- [ ] **Konfiguration:**
- [ ] `.env` Variablen dokumentiert (falls neu)
- [ ] Config-Dateien (`types.yaml`, etc.) kompatibel
- [ ] Edge Registry Pfad korrekt
- [ ] **Datenbank:**
- [ ] Schema-Änderungen dokumentiert
- [ ] Migration-Skripte vorhanden (falls nötig)
- [ ] Backup erstellt
- [ ] **Dokumentation:**
- [ ] Changelog aktualisiert
- [ ] Dokumentation synchronisiert
- [ ] Breaking Changes dokumentiert
---
## 8. Post-Deployment Validierung
Nach jedem Deployment sollten folgende Checks durchgeführt werden:
### 8.1 Service-Status
```bash
# Services laufen
sudo systemctl status mindnet-prod
sudo systemctl status mindnet-ui-prod
# Health Check
curl http://localhost:8001/healthz
```
### 8.2 Funktionalität
```bash
# API-Test
curl -X POST http://localhost:8001/query \
-H "Content-Type: application/json" \
-d '{"query": "test", "top_k": 1}'
# UI-Test (Manuell)
# Öffne http://localhost:8501 im Browser
```
### 8.3 Logs prüfen
```bash
# Fehler in Logs
sudo journalctl -u mindnet-prod --since "5 minutes ago" | grep -i error
# Warnings
sudo journalctl -u mindnet-prod --since "5 minutes ago" | grep -i warning
```
---
## 9. CI/CD Pipeline Details
### 9.1 Gitea Actions Workflow
**Datei:** `.gitea/workflows/deploy.yml`
**Trigger:**
- Push auf `main` Branch
- Concurrency: Nur ein Deployment gleichzeitig
**Schritte:**
1. **Checkout:** Code aus Repository
2. **Stop API:** Graceful Stop (continue-on-error)
3. **Deploy:** Rsync der Verzeichnisse
4. **Python Setup:** Venv & Requirements
5. **Start API:** Service neu starten
**Wichtig:**
- `.env` wird **nicht** deployed (bleibt auf Server)
- Vault wird **nicht** deployed (bleibt auf Server)
### 9.2 Deployment-Verzeichnisse
**Whitelist:**
```
app scripts schemas docker tests config requirements.txt README.md
```
**Excluded:**
- `.git/`
- `.env*`
- `.venv/`
- `vault/`
- `hf_cache/`
---
## 10. Monitoring & Alerting
### 10.1 Health Checks
**API Health Endpoint:**
```bash
curl http://localhost:8001/healthz
```
**Response:**
```json
{
"status": "ok",
"qdrant": "http://localhost:6333",
"prefix": "mindnet"
}
```
**Monitoring-Script:**
```bash
python3 -m scripts.health_check_mindnet --url http://localhost:8001 --strict
```
### 10.2 Log-Monitoring
**Systemd Journal:**
```bash
# Live-Logs
sudo journalctl -u mindnet-prod -f
# Letzte 100 Zeilen
sudo journalctl -u mindnet-prod -n 100
# Seit gestern
sudo journalctl -u mindnet-prod --since "yesterday"
```
### 10.3 Metriken (Zukünftig)
**Geplante Metriken:**
- Request-Rate
- Response-Zeiten
- Fehler-Rate
- LLM-Call-Dauer
- Qdrant-Performance
**Tools:** Prometheus + Grafana (noch nicht implementiert)
---
## 11. Disaster Recovery
Siehe [Server Operations Manual](04_server_operation_manual.md#5-disaster-recovery-wiederherstellung-two-stage-dr) für detaillierte Disaster-Recovery-Prozeduren.
**Kurzfassung:**
1. **Stage 1:** Basis-Image Restore (Bare Metal)
2. **Stage 2:** Daten-Update via Borgmatic
3. **Dienste:** Gitea, Qdrant, Ollama spezifisch wiederherstellen
---
## 12. Best Practices
### 12.1 Deployment-Zeiten
- **Produktion:** Während Wartungsfenstern (nachts, Wochenenden)
- **Development:** Jederzeit (ist Test-Umgebung)
### 12.2 Kommunikation
- **Breaking Changes:** Vorher ankündigen
- **Downtime:** Bei größeren Deployments kommunizieren
- **Rollback-Plan:** Immer bereit haben
### 12.3 Testing
- **Immer zuerst auf Dev testen**
- **Smoke Tests nach Deployment**
- **Monitoring für erste Stunden nach Deployment**
---
## 13. Weitere Informationen
- **Admin Operations:** Siehe [Admin Operations Guide](04_admin_operations.md)
- **Server Operations:** Siehe [Server Operations Manual](04_server_operation_manual.md)
- **Troubleshooting:** Siehe [Admin Operations - Troubleshooting](04_admin_operations.md#33-troubleshooting-guide)
---
**Letzte Aktualisierung:** 2025-01-XX
**Version:** 2.9.1
+57 -7
View File
@@ -1,10 +1,10 @@
---
doc_type: developer_guide
audience: developer
scope: workflow, testing, architecture, modules, modularization
scope: workflow, testing, architecture, modules, modularization, agentic_rag, lazy_prompts
status: active
version: 2.9.1
context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), Modul-Interna, Setup und Git-Workflow."
version: 3.1.1
context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), WP-25 Agentic Multi-Stream RAG, WP-25a MoE, WP-25b Lazy-Prompt-Orchestration, Modul-Interna, Setup und Git-Workflow."
---
# Mindnet Developer Guide & Workflow
@@ -216,11 +216,27 @@ Das Frontend ist eine Streamlit-App, die sich wie eine Single-Page-Application (
Das Backend ist das Herzstück. Es stellt die Logik via REST-API bereit.
**Wichtig:** Seit WP-14 ist die Core-Logik in spezialisierte Pakete unterteilt:
#### Core-Pakete (Modularisierung WP-14)
| Paket | Zweck | Wichtige Module |
| :--- | :--- | :--- |
| **`app/core/chunking/`** | Text-Segmentierung | `chunking_strategies.py` (Sliding/Heading), `chunking_processor.py` (Orchestrierung) |
| **`app/core/database/`** | Qdrant-Infrastruktur | `qdrant.py` (Client), `qdrant_points.py` (Point-Mapping) |
| **`app/core/graph/`** | Graph-Logik | `graph_subgraph.py` (Expansion), `graph_weights.py` (Scoring) |
| **`app/core/ingestion/`** | Import-Pipeline | `ingestion_processor.py` (Two-Pass), `ingestion_validation.py` (Mistral-safe Parsing) |
| **`app/core/parser/`** | Markdown-Parsing | `parsing_markdown.py` (Frontmatter/Body), `parsing_scanner.py` (File-Scan) |
| **`app/core/retrieval/`** | Suche & Scoring | `retriever.py` (Orchestrator), `retriever_scoring.py` (Mathematik) |
| **`app/core/registry.py`** | SSOT & Utilities | Text-Bereinigung, Circular-Import-Fix |
**Legacy-Bridges:** Die alten Dateien (`app/core/retriever.py`, `app/core/qdrant.py`) existieren noch als Proxy-Adapter für Abwärtskompatibilität, delegieren aber an die neuen Pakete.
| Layer | Datei | Status | Verantwortung |
| :--- | :--- | :--- | :--- |
| **Entry** | `app/main.py` | 🟢 **Core** | **Entrypoint.** Initialisiert FastAPI, CORS, und bindet alle Router ein. |
| **Config** | `app/config.py` | 🟢 **Core** | **Settings.** Zentrale Konfiguration (Pydantic). Lädt Env-Vars für Qdrant, LLM und Pfade. |
| **Router** | `app/routers/chat.py` | 🟢 **API** | **Conversation API.** Haupt-Endpunkt für Chat. Entscheidet zwischen Interview- und RAG-Modus. |
| **Router** | `app/routers/chat.py` | 🟢 **API** | **Conversation API (WP-25).** Haupt-Endpunkt für Chat. Hybrid Router mit Intent-Erkennung, Multi-Stream Orchestration und Wissens-Synthese. |
| | `app/routers/ingest.py` | 🟢 **API** | **Write API.** Nimmt Markdown entgegen, steuert Ingestion und Discovery-Analyse. |
| | `app/routers/query.py` | 🟢 **API** | **Search API.** Klassischer Hybrid-Retriever Endpunkt. |
| | `app/routers/graph.py` | 🟢 **API** | **Viz API.** Liefert Knoten/Kanten für Frontend-Graphen (Cytoscape). |
@@ -377,12 +393,46 @@ Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration*
edge_defaults: ["blocks"] # Automatische Kante
detection_keywords: ["gefahr", "risiko"]
```
2. **Strategie (`config/decision_engine.yaml`):**
2. **Strategie (`config/decision_engine.yaml` v3.2.2, WP-25/25a):**
```yaml
DECISION:
inject_types: ["value", "risk"] # <--- "risk" hinzufügen
use_streams: ["values_stream", "facts_stream", "risk_stream"] # WP-25: Multi-Stream
llm_profile: "synthesis_pro" # WP-25a: MoE-Profil für Synthese
inject_types: ["value", "risk"] # Legacy: Fallback für nicht-Stream-Typen
```
*Ergebnis:* Wenn der Intent `DECISION` erkannt wird, sucht das System nun auch aktiv nach Risiken.
*Ergebnis (WP-25/25a):* Wenn der Intent `DECISION` erkannt wird, führt das System parallele Abfragen in Values, Facts und Risk Streams aus, komprimiert überlange Streams via `compression_profile` und synthetisiert die Ergebnisse mit dem `synthesis_pro` Profil.
3. **LLM-Profil (`config/llm_profiles.yaml` v1.3.0, WP-25a):**
```yaml
synthesis_pro:
provider: "openrouter"
model: "google/gemini-2.0-flash-exp:free"
temperature: 0.7
fallback_profile: "synthesis_backup"
```
*Ergebnis (WP-25a):* Zentrale Steuerung von Provider, Modell und Temperature pro Aufgabe. Automatische Fallback-Kaskade bei Fehlern.
4. **Prompt-Template (`config/prompts.yaml` v3.2.2, WP-25b):**
```yaml
decision_synthesis_v1:
# Level 1: Modell-spezifisch (höchste Priorität)
"google/gemini-2.0-flash-exp:free": |
WERTE & PRINZIPIEN (Identität):
{values_stream}
...
# Level 2: Provider-Fallback
openrouter: |
WERTE & PRINZIPIEN (Identität):
{values_stream}
...
# Level 3: Global Default
default: |
Synthetisiere die folgenden Informationen für: {query}
...
```
*Ergebnis (WP-25b):* Hierarchische Prompt-Resolution mit Lazy-Loading. Prompts werden erst zur Laufzeit geladen, basierend auf aktivem Modell. Maximale Resilienz bei Modell-Fallbacks.
### Workflow B: Graph-Farben ändern
1. Öffne `app/frontend/ui_config.py`.
+402
View File
@@ -0,0 +1,402 @@
---
doc_type: developer_guide
audience: developer, tester
scope: testing, quality_assurance, test_strategies
status: active
version: 2.9.3
context: "Umfassender Test-Guide für Mindnet: Test-Strategien, Test-Frameworks, Test-Daten und Best Practices inklusive WP-25 Multi-Stream RAG."
---
# Testing Guide
Dieses Dokument beschreibt die Test-Strategien, Test-Frameworks und Best Practices für die Qualitätssicherung von Mindnet.
## 1. Test-Strategie & Ebenen
Mindnet nutzt eine **dreistufige Test-Pyramide**:
```
/\
/E2E\ ← Wenige, langsame, teure Tests
/------\
/Integration\ ← Mittlere Anzahl, mittlere Geschwindigkeit
/------------\
/ Unit Tests \ ← Viele, schnelle, isolierte Tests
/----------------\
```
### 1.1 Unit Tests (Pytest)
**Zweck:** Isolierte Logik-Tests ohne externe Abhängigkeiten.
**Framework:** `pytest`
**Beispiele:**
- `tests/test_retriever_basic.py` - Scoring-Logik
- `tests/test_chunking.py` - Chunking-Strategien
- `tests/test_edges_all.py` - Edge-Logik
- `tests/test_type_registry.py` - Registry-Funktionen
**Ausführung:**
```bash
# Einzelner Test
pytest tests/test_retriever_basic.py -v
# Alle Unit Tests
pytest tests/ -k "test_" --ignore=tests/test_*_smoke.py
# Mit Coverage
pytest tests/ --cov=app --cov-report=html
```
**Best Practices:**
- Tests sollten isoliert sein (keine Abhängigkeiten zu Qdrant/Ollama)
- Mock externe Services (LLM, Qdrant)
- Schnelle Ausführung (< 1 Sekunde pro Test)
### 1.2 Integration Tests
**Zweck:** Prüfen den Datenfluss von Markdown bis Qdrant.
**Tools:**
- `scripts/payload_dryrun.py` - JSON-Schema-Konformität
- `scripts/edges_full_check.py` - Graph-Integrität
- `scripts/make_test_vault.py` - Test-Daten-Generierung
**Ausführung:**
```bash
# Payload-Validierung
python3 -m scripts.payload_dryrun --vault ./test_vault --with-edges
# Graph-Integrität
python3 -m scripts.edges_full_check
# Test-Vault erstellen
python3 -m scripts.make_test_vault --out ./test_vault --force
```
**Was wird geprüft:**
- Frontmatter-Parsing
- Chunk-Generierung
- Edge-Erstellung
- Payload-Schema-Konformität
- Graph-Invarianten (keine Dangling Edges)
### 1.3 E2E / Smoke Tests
**Zweck:** Prüfen das laufende System gegen echte Infrastruktur (Qdrant, Ollama).
**Framework:** Python `unittest` + Shell-Skripte
**Beispiele:**
- `tests/test_wp06_decision.py` - Decision Engine
- `tests/test_feedback_smoke.py` - Feedback-Loop
- `tests/test_dialog_full_flow.py` - Vollständiger Dialog-Flow
- `tests/run_e2e_roundtrip.sh` - Kompletter Roundtrip (Import → Export)
**Ausführung:**
```bash
# Decision Engine Test
python tests/test_wp06_decision.py -p 8002 -e DECISION -q "Soll ich X tun?"
# Feedback Test
python tests/test_feedback_smoke.py --url http://localhost:8002/query
# E2E Roundtrip
./tests/run_e2e_roundtrip.sh --vault ./test_vault --prefix mindnet_test
```
**Voraussetzungen:**
- Qdrant läuft auf `localhost:6333`
- Ollama läuft auf `localhost:11434`
- API läuft auf Port 8002 (Dev)
---
## 2. Test-Daten & Vaults
### 2.1 Test-Vault erstellen
**Tool:** `scripts/make_test_vault.py`
**Zweck:** Erstellt einen minimalen, nachvollziehbaren Test-Vault.
**Inhalt:**
- Verschiedene Note-Typen (`concept`, `experience`, `project`)
- Verschiedene Edge-Szenarien (explicit, implicit, missing links)
- Externe Links für Edge-Tests
**Verwendung:**
```bash
# Standard
python3 -m scripts.make_test_vault --out ./test_vault
# Mit fehlenden Links (für Link-Auflösungs-Tests)
python3 -m scripts.make_test_vault --out ./test_vault --with-missing
# Überschreiben bestehenden Vault
python3 -m scripts.make_test_vault --out ./test_vault --force
```
### 2.2 Test-Collection Prefix
**Wichtig:** Nutze separate Prefixes für Tests, um Produktionsdaten nicht zu beeinflussen.
```bash
export COLLECTION_PREFIX="mindnet_test"
python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet_test --apply
```
---
## 3. Test-Frameworks & Tools
### 3.1 Pytest (Unit Tests)
**Installation:**
```bash
pip install pytest pytest-asyncio pytest-cov
```
**Konfiguration:** `pytest.ini` oder `pyproject.toml`
**Async Tests:**
```python
import pytest
@pytest.mark.asyncio
async def test_async_function():
result = await async_function()
assert result == expected
```
### 3.2 Unittest (E2E Tests)
**Framework:** Python `unittest`
**Beispiel:**
```python
import unittest
from app.routers.ingest import save_note, SaveRequest
class TestIngest(unittest.IsolatedAsyncioTestCase):
async def test_save_note(self):
req = SaveRequest(markdown_content="...", filename="test.md")
response = await save_note(req)
self.assertEqual(response.status, "queued")
```
### 3.3 Shell-Skripte (E2E Roundtrip)
**Tool:** `tests/run_e2e_roundtrip.sh`
**Zweck:** Vollständiger Test-Zyklus (Import → Export → Vergleich)
**Schritte:**
1. Qdrant truncate
2. Import (Create-Fall)
3. Import (Idempotenz-Test)
4. Hash-Reporter
5. Export
6. Vergleich Vault vs. Export
7. Sync-Deletes Test
---
## 4. Test-Szenarien
### 4.1 Chunking-Tests
**Was wird getestet:**
- Sliding Window Strategie
- Heading-basierte Strategie
- Edge-Vererbung
- Chunk-Größen-Limits
**Tests:**
- `tests/test_smart_chunking_integration.py`
- `scripts/preview_chunks.py` (Manuelle Inspektion)
### 4.2 Retrieval-Tests
**Was wird getestet:**
- Semantic Search
- Hybrid Search (Semantik + Graph)
- Scoring-Formel
- Explanation Layer
**Tests:**
- `tests/test_retriever_basic.py`
- `tests/test_retriever_edges.py`
- `tests/test_retriever_weight.py`
- `tests/test_explanation_smoke.py`
### 4.3 Edge-Tests
**Was wird getestet:**
- Edge-Erstellung (explicit, smart, rule)
- Edge-Validierung (Registry)
- Edge-Vererbung
- Unresolved References
**Tests:**
- `tests/test_edges_all.py`
- `tests/test_edges_smoke.py`
- `tests/test_edges_defaults_smoke.py`
- `scripts/edges_full_check.py`
### 4.4 Chat & Intent-Tests (WP-25)
**Was wird getestet:**
- Intent-Erkennung (FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW)
- Hybrid Router (Keyword Fast-Path + LLM Slow-Path)
- Decision Engine (Multi-Stream Orchestration)
- Parallele Stream-Abfragen (Values, Facts, Biography, Risk, Tech)
- Stream-Tracing (`stream_origin` Markierung)
- Wissens-Synthese (Template-basierte Zusammenführung)
- Interview-Modus
- Feedback-Loop
**Tests:**
- `tests/test_wp06_decision.py` - Decision Engine (Legacy)
- `tests/test_interview_intent.py` - Interview-Modus
- `tests/test_chat_wp05.py` - Chat-Backend (Legacy)
- `tests/test_feedback_smoke.py` - Feedback-Loop
**WP-25 Spezifische Tests (geplant):**
- Multi-Stream Retrieval (parallele Abfragen)
- Stream-Tracing (stream_origin Zuordnung)
- Template-Robustheit (Pre-Initialization)
- Intent-Kollision (Keyword-Fast-Path Präzision)
### 4.5 Ingestion-Tests
**Was wird getestet:**
- Two-Pass Workflow
- Change Detection (Hash-basiert)
- Background Tasks
- Smart Edge Allocation
**Tests:**
- `tests/test_dialog_full_flow.py`
- `tests/test_WP22_intelligence.py`
- `scripts/import_markdown.py` (mit `--dry-run`)
---
## 5. Continuous Integration
### 5.1 Pre-Commit Checks
**Empfohlene Checks:**
```bash
# Linting
flake8 app/ scripts/
# Type Checking (optional)
mypy app/
# Unit Tests
pytest tests/ -k "test_" --ignore=tests/test_*_smoke.py
```
### 5.2 CI/CD Pipeline
**Gitea Actions:** `.gitea/workflows/`
**Typische Pipeline:**
1. Checkout
2. Python Setup
3. Dependencies installieren
4. Unit Tests
5. Integration Tests (optional)
6. Deployment (bei main branch)
---
## 6. Test-Best Practices
### 6.1 Isolation
- **Unit Tests:** Keine externen Abhängigkeiten (Mock alles)
- **Integration Tests:** Echte Qdrant, aber isolierte Collections
- **E2E Tests:** Separate Test-Umgebung (Port 8002)
### 6.2 Test-Daten
- Nutze `make_test_vault.py` für konsistente Test-Daten
- Separate Collection-Prefixes für Tests
- Cleanup nach Tests (oder isolierte Collections)
### 6.3 Performance
- Unit Tests sollten < 1 Sekunde dauern
- Integration Tests können länger dauern (10-30 Sekunden)
- E2E Tests sind langsam (1-5 Minuten)
### 6.4 Wartbarkeit
- Klare Test-Namen (`test_<functionality>_<scenario>`)
- Dokumentation in Test-Docstrings
- Keine Hardcoded-Pfade (nutze `os.path`)
---
## 7. Debugging & Diagnose
### 7.1 Test-Debugging
**Pytest Debug-Modus:**
```bash
pytest tests/test_retriever_basic.py -v --pdb
```
**Einzelnen Test inspizieren:**
```bash
python3 -m scripts.payload_dryrun --vault ./test_vault --note-id "test-note"
```
### 7.2 Qdrant-State prüfen
```bash
# Collection-Status
python3 -m scripts.debug_qdrant_state --prefix mindnet_test
# Payload-Indexe prüfen
python3 -m scripts.diag_payload_indexes --prefix mindnet_test
```
### 7.3 Chunk-Inspektion
```bash
# Chunks für eine Note anzeigen
python3 -m scripts.dump_note_chunks --note-id "test-note" --prefix mindnet_test
# Chunk-Text-Verifikation
python3 -m scripts.verify_chunk_texts --prefix mindnet_test
```
---
## 8. Test-Checkliste für Pull Requests
Vor jedem PR sollten folgende Tests durchlaufen:
- [ ] Unit Tests: `pytest tests/ -k "test_" --ignore=tests/test_*_smoke.py`
- [ ] Payload-Validierung: `python3 -m scripts.payload_dryrun --vault ./test_vault`
- [ ] Graph-Integrität: `python3 -m scripts.edges_full_check`
- [ ] Smoke Test (wenn API läuft): `python tests/test_wp06_decision.py -p 8002`
---
## 9. Weitere Informationen
- **Developer Guide:** Siehe [Developer Guide](05_developer_guide.md)
- **Scripts-Übersicht:** Siehe [Developer Guide - Scripts](05_developer_guide.md#44-scripts--tooling-die-admin-toolbox)
- **Troubleshooting:** Siehe [Admin Operations - Troubleshooting](../04_Operations/04_admin_operations.md#33-troubleshooting-guide)
---
**Letzte Aktualisierung:** 2025-01-XX
**Version:** 2.9.1
+45 -42
View File
@@ -2,14 +2,14 @@
doc_type: roadmap
audience: product_owner, developer
status: active
version: 2.9.1
context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b."
version: 3.1.1
context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b/15c/25/25a/25b."
---
# Mindnet Active Roadmap
**Aktueller Stand:** v2.9.1 (Post-WP14 / WP-15b)
**Fokus:** Modularisierung, Two-Pass Ingestion & Graph Intelligence.
**Aktueller Stand:** v3.1.1 (Post-WP25b: Lazy-Prompt-Orchestration & Full Resilience)
**Fokus:** Hierarchische Prompt-Resolution, Modell-spezifisches Tuning & maximale Resilienz.
| Phase | Fokus | Status |
| :--- | :--- | :--- |
@@ -48,6 +48,10 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio
| **WP-20** | **Cloud Hybrid Mode & Resilienz** | **Ergebnis:** Integration von OpenRouter (Mistral 7B) & Gemini 2.5 Lite. Implementierung von WP-76 (Rate-Limit Wait) & Mistral-safe JSON Parsing. |
| **WP-21** | Semantic Graph Routing & Canonical Edges | Transformation des Graphen von statischen Verbindungen zu dynamischen, kontextsensitiven Pfaden. Das System soll verstehen, *welche* Art von Verbindung für die aktuelle Frage relevant ist ("Warum?" vs. "Was kommt danach?"). |
| **WP-22** | **Content Lifecycle & Registry** | **Ergebnis:** SSOT via `01_edge_vocabulary.md`, Alias-Mapping, Status-Scoring (`stable`/`draft`) und Modularisierung der Scoring-Engine. |
| **WP-15c** | **Multigraph-Support & Diversity Engine** | **Ergebnis:** Section-basierte Links, Note-Level Diversity Pooling, Super-Edge Aggregation, Provenance Firewall. Transformation zu einem hochpräzisen Multigraphen. |
| **WP-25** | **Agentic Multi-Stream RAG Orchestration** | **Ergebnis:** Übergang von linearer RAG-Architektur zu paralleler Multi-Stream Engine. Intent-basiertes Routing (Hybrid Fast/Slow-Path), parallele Wissens-Streams (Values, Facts, Biography, Risk, Tech), Stream-Tracing und Template-basierte Wissens-Synthese. |
| **WP-25a** | **Mixture of Experts (MoE) & Fallback-Kaskade** | **Ergebnis:** Profilbasierte Experten-Architektur, rekursive Fallback-Kaskade, Pre-Synthesis Kompression, profilgesteuerte Ingestion und Embedding-Konsolidierung. |
| **WP-25b** | **Lazy-Prompt-Orchestration & Full Resilience** | **Ergebnis:** Hierarchisches Prompt-Resolution-System (3-stufig), Lazy-Prompt-Loading, ultra-robustes Intent-Parsing, differenzierte Ingestion-Validierung und PROMPT-TRACE Logging. |
### 2.1 WP-22 Lessons Learned
* **Architektur:** Die Trennung von `retriever.py` und `retriever_scoring.py` war notwendig, um LLM-Context-Limits zu wahren und die Testbarkeit der mathematischen Formeln zu erhöhen.
@@ -191,53 +195,52 @@ Der bisherige WP-15 Ansatz litt unter Halluzinationen (erfundene Kantentypen), h
2. **Single Source of Truth (SSOT):** Die Registry nutzt `01_edge_vocabulary.md` als führende Konfiguration.
3. **Self-Learning Loop:** Protokollierung unbekannter Kanten in `unknown_edges.jsonl`.
### WP-23: Agentic Multi-Stream Reasoning (Mindnet 2025)
### WP-25: Agentic Multi-Stream RAG Orchestration
**Status:** ✅ Fertig (v3.0.0)
#### 1. Zielsetzung & Problemstellung
Das bisherige System basiert auf einem globalen Scoring-Modell, bei dem Notizen unterschiedlicher Typen (z. B. `insight` vs. `belief`) in einem einzigen Retrieval-Topf konkurrieren. Dies führt dazu, dass leiser gewichtete, aber fundamentale Identitätsmerkmale oft durch hochgewichtete aktuelle Erkenntnisse verdrängt werden. Ziel dieses Pakets ist die Einführung einer parallelen **Stream-Architektur**, um die Vielschichtigkeit menschlicher Entscheidungsprozesse (Werte + Erfahrung + Absicht) im LLM-Kontext zu garantieren.
### WP-25a: Mixture of Experts (MoE) & Fallback-Kaskade
**Status:** ✅ Fertig (v3.1.0)
#### 2. Funktionsbeschreibung: Die Streams
Die Daten aus der `types.yaml` werden in drei logische Verarbeitungseinheiten unterteilt:
**Ergebnis:** Transformation von MindNet von einer provider-basierten Steuerung auf eine **profilbasierte Experten-Architektur (Mixture of Experts)**. Jede Systemaufgabe wird einem dedizierten Profil zugewiesen, das Modell, Provider und Parameter unabhängig definiert.
##### A. Identity Stream (Die Wahrheitsebene)
* **Inhalt:** `value`, `belief`, `trait`, `principle`, `need`, `boundary`, `bias`.
* **Zweck:** Definition des moralischen Kompasses, der psychologischen Grundbedürfnisse und kognitiven Muster.
* **Wirkung:** Liefert das "Warum" hinter jeder Handlung.
**Kern-Features:**
1. **Experten-Steuerung:** Zentrale Profile-Registry (`llm_profiles.yaml`) für alle LLM-Aufgaben
2. **Rekursive Fallback-Kaskade:** Automatische Resilienz bei Provider-Fehlern mit Schutz gegen Zirkel-Referenzen
3. **Pre-Synthesis Kompression:** Asynchrone Verdichtung überlanger Wissens-Streams vor der Synthese
4. **Profilgesteuerte Ingestion:** Deterministische Validierung via `ingest_validator` (Temperature 0.0)
5. **Embedding-Konsolidierung:** Zentrale Steuerung des Embedding-Modells über `embedding_expert` Profil
6. **Startup-Schutz:** Validierung der YAML-Konfigurationen beim Booten
##### B. History Stream (Die Evidenzebene)
* **Inhalt:** `experience`, `event`, `source`, `journal`, `person`.
* **Zweck:** Bereitstellung empirischer Belege aus der Vergangenheit und sozialer Kontexte.
* **Wirkung:** Verankert die Antwort in real erlebten Mustern und Fakten.
**Technische Details:**
- LLM Service v3.5.2: Rekursive Fallback-Kaskade
- Decision Engine v1.2.1: Profile-Driven Orchestration
- Ingestion Processor v2.14.0: Profilgesteuerte Validierung
- Embeddings Client v2.6.0: Profil-basierte Modell-Auflösung
- llm_profiles.yaml v1.3.0: Zentrale Experten-Registry
- decision_engine.yaml v3.2.2: Decoupled MoE Logic
##### C. Action Stream (Die Dynamikebene)
* **Inhalt:** `project`, `decision`, `goal`, `task`, `risk`, `motivation`, `habit`, `state`.
* **Zweck:** Analyse der aktuellen Richtung, geplanter Vorhaben und des gegenwärtigen Zustands.
* **Wirkung:** Liefert den Kontext für die Umsetzung und zukünftige Ziele.
### WP-25b: Lazy-Prompt-Orchestration & Full Resilience
**Status:** ✅ Fertig (v3.1.1)
**Ergebnis:** Umstellung von statischer Prompt-Formatierung auf eine **hierarchische Lazy-Prompt-Orchestration**. Prompts werden erst im Moment des Modellaustauschs geladen, basierend auf dem exakt aktiven Modell. Dies ermöglicht modell-spezifisches Tuning und maximale Resilienz bei Modell-Fallbacks.
#### 3. Technische Wirkungsweise (Solution Sketch)
**Kern-Features:**
1. **Hierarchisches Prompt-Resolution-System:** Dreistufige Auflösung (Modell-ID → Provider → Default)
2. **Lazy-Loading:** Prompts werden erst zur Laufzeit geladen, wenn das aktive Modell bekannt ist
3. **Ultra-robustes Intent-Parsing:** Regex-basierter Parser bereinigt Modell-Artefakte (z.B. `CODING[/S]` → `CODING`)
4. **Differenzierte Ingestion-Validierung:** Unterscheidung zwischen transienten (Netzwerk) und permanenten (Config) Fehlern
5. **PROMPT-TRACE Logging:** Vollständige Transparenz über genutzte Instruktionen
##### Schritt 1: Query-Decomposition
Ein initialer Klassifizierungs-Agent analysiert die Nutzeranfrage und bestimmt, welcher Stream primär angesprochen werden muss (z. B. "Wie soll ich mich entscheiden?" boostet den Identity Stream).
**Technische Details:**
- LLM Service v3.5.5: Hierarchische Prompt-Resolution mit Lazy-Loading
- Decision Engine v1.3.2: Ultra-robustes Intent-Parsing via Regex
- Ingestion Validation v2.14.0: Lazy-Prompt-Integration, differenzierte Fehlerbehandlung
- prompts.yaml v3.2.2: Hierarchische Struktur mit Modell-spezifischen Overrides
##### Schritt 2: Parallel Stream Retrieval
Anstelle einer Suche werden drei unabhängige Vektor-Suchen mit Typ-Filtern durchgeführt:
* **Search_A (Identity):** Top-5 Ergebnisse aus Identitäts-Notizen.
* **Search_B (History):** Top-5 Ergebnisse aus biografischen/externen Notizen.
* **Search_C (Action):** Top-5 Ergebnisse aus operativen/strategischen Notizen.
##### Schritt 3: Agentic Synthesis (The Reasoning)
Ein Synthese-Agent (LLM) erhält die aggregierten Ergebnisse in getrennten Sektionen. Die Anweisung lautet:
1. **Prüfung:** Steht das aktuelle Vorhaben (Action) im Einklang mit den Werten (Identity)?
2. **Abgleich:** Welche vergangenen Erfahrungen (History) stützen oder widersprechen diesem Weg?
3. **Korrektur:** Identifiziere mögliche Biases oder Grenzüberschreitungen (Boundary).
#### 4. Erwartete Ergebnisse
* **Höhere Resonanz:** Antworten wirken authentischer, da sie explizit auf das Wertesystem des Nutzers Bezug nehmen.
* **Widerspruchs-Erkennung:** Das System kann den Nutzer aktiv warnen, wenn ein Projekt gegen seine `principles` oder `needs` verstößt.
* **Robustes Retrieval:** Wichtige Identitäts-Informationen gehen nicht mehr im "Rauschen" von hunderten Journal-Einträgen verloren.
**Ausblick (WP-25c):**
- Kontext-Budgeting: Intelligente Token-Verteilung
- Stream-specific Provider: Unterschiedliche KI-Modelle pro Wissensbereich
- Erweiterte Prompt-Optimierung: Dynamische Anpassung basierend auf Kontext und Historie
---
### WP-24 – Proactive Discovery & Agentic Knowledge Mining
+86 -10
View File
@@ -254,6 +254,9 @@ Bitte bestätige die Übernahme, erstelle die `edge_mappings.yaml` Struktur und
* Es ist der logisch perfekte Ort, um zu sagen: "Wenn der User im Analyse-Modus ist, sind Fakten-Kanten wichtiger als Gefühls-Kanten."
Damit hast du das perfekte Paket für den nächsten Entwicklungsschritt geschnürt!
```
---
## WP-22: Content Lifecycle & Meta-Config
@@ -271,8 +274,6 @@ Wir haben eine Markdown-Datei (`01_edge_vocabulary.md`), die als Single-Source-o
**Dein Auftrag:**
Implementiere (A) den Content-Lifecycle, (B) die Edge-Registry und (C) das Semantic Routing.
---
### Teil A: Content Lifecycle (Ingestion Logic)
Steuerung über Frontmatter `status`:
1. **System-Dateien (No-Index):**
@@ -281,8 +282,6 @@ Steuerung über Frontmatter `status`:
* Wenn `status` in `['draft', 'active', 'stable']`: Status wird im Payload gespeichert.
* **ToDo:** Erweitere `scoring.py`, damit `stable` Notizen einen Bonus erhalten (`x 1.2`), `drafts` einen Malus (`x 0.5`).
---
### Teil B: Central Edge Registry & Validation
1. **Registry Klasse:**
* Erstelle `EdgeRegistry` (Singleton).
@@ -292,8 +291,6 @@ Steuerung über Frontmatter `status`:
* Prüfe beim Import jede Kante gegen die Registry.
* Unbekannte Typen werden **nicht** verworfen, sondern in `data/logs/unknown_edges.jsonl` geloggt (für späteres Review).
---
### Teil C: Semantic Graph Routing (Dynamic Boosting)
**Ziel:** Die Bedeutung einer Kante soll sich je nach Frage-Typ ändern ("Warum" vs. "Wie").
@@ -308,7 +305,6 @@ Die Gewichtung findet **Pre-Retrieval** (im Scoring-Algorithmus) statt, **nicht*
* Der `Retriever` erhält vom Router die `boost_edges` Map.
* Berechne Score: `BaseScore * (1 + ConfigWeight + DynamicBoost)`.
---
**Deine Aufgaben:**
1. Zeige die `EdgeRegistry` Klasse (Parsing Logik).
@@ -316,10 +312,12 @@ Die Gewichtung findet **Pre-Retrieval** (im Scoring-Algorithmus) statt, **nicht*
3. Zeige die Erweiterung in `scoring.py` (Status-Gewicht & Dynamic Edge Boosting).
Bitte bestätige die Übernahme dieses Architektur-Pakets.
```
---
## WP24
```text
# Übergabe Arbeitspaket: WP-24 – Proactive Discovery & Agentic Knowledge Mining
Übergabe Arbeitspaket: WP-24 – Proactive Discovery & Agentic Knowledge Mining
## 1. Projekt-Kontext
Wir arbeiten an **Mindnet**, einem System für einen "digitalen Zwilling". Das System nutzt einen Wissensgraph (Qdrant), asynchrone Ingestion und eine hybride LLM-Infrastruktur (Cloud/Lokal).
@@ -356,4 +354,82 @@ Stelle sicher, dass dir folgende Dateien vorliegen, um die Logik zu verstehen un
## 5. Nächste technische Schritte
1. Entwurf eines `RecommenderService` für die Vektor-Suche in Qdrant.
2. Integration des Services in die `ingestion.py` zur automatischen Befüllung des `candidate_pool`.
3. Erweiterung des Chat-Backends um die "Capture-to-Vault" Funktionalität.
3. Erweiterung des Chat-Backends um die "Capture-to-Vault" Funktionalität.
```
## WP-25: Advanced Reasoning Engine (Agentic RAG)
``` Text
**Status:** 🚀 High-Priority Upgrade
**Ziel:** Implementierung einer mehrstufigen Entscheidungs-Architektur ("Multi-Hop").
**Das Problem:**
Single-Step-Retrieval verwässert Ergebnisse. Eine Suche nach "Projekt-Entscheidung" findet oft operative Details, übersieht aber fundamentale Werte ("Wertekompass"), weil diese semantisch distanziert sind.
**Die Lösung (Architektur):**
Wir ersetzen die flache Suche durch eine **Orchestrator-Logik**, die parallele Streams ausführt.
---
### Teil A: Configuration Upgrade (`decision_engine.yaml`)
Erweitere die Config-Struktur, um statt einfacher Listen echte **Sub-Queries** zu definieren.
*Neu (Vorschlag):*
````yaml
strategies:
DECISION:
description: "Komplexe Abwägung"
# Der Orchestrator führt diese 3 Streams parallel aus:
streams:
- name: "facts"
query_template: "Status und Fakten zu: {query}"
filter_types: ["project", "journal", "decision"]
edge_boosts: {part_of: 1.5}
- name: "values"
query_template: "Welche Werte und Prinzipien sind relevant für: {query}"
filter_types: ["value", "principle", "belief"]
edge_boosts: {derived_from: 2.0, enforced_by: 2.0} # Findet den "Wertekompass"!
- name: "risks"
query_template: "Risiken und Gefahren bei: {query}"
filter_types: ["risk", "obstacle"]
edge_boosts: {blocks: 2.5, impacts: 2.0}
````
``` Text
### Teil B: Implementation (`DecisionEngine.py`)
1. **Decomposition:** Wenn eine Strategie `streams` definiert, darf nicht mehr *ein* `retrieve()` Aufruf erfolgen.
2. **Parallel Execution:**
* Iteriere über alle Streams.
* Führe für jeden Stream einen eigenen `retriever.retrieve()` aus – mit dessen spezifischen Filtern, Query und Edge-Boosts.
3. **Intermediate Summarization (Optional/Later):**
* (Für Version 1 reicht es, die Ergebnisse der Streams in markierten Blöcken an den Prompt zu geben).
### Teil C: The Synthesis (Prompting)
Passe das Prompt-Template an, um die getrennten Streams zu nutzen:
...
HIER SIND DIE FAKTEN:
{stream_results_facts}
HIER SIND DIE RELEVANTEN WERTE/PRINZIPIEN:
{stream_results_values}
HIER SIND DIE RISIKEN:
{stream_results_risks}
AUFGABE: Wäge die Fakten gegen die Werte ab.
```
---
**Deine Aufgaben:**
1. **Refactor Config:** Zeige, wie die `decision_engine.yaml` für Multi-Stream angepasst wird.
2. **Orchestrator Logic:** Schreibe die Python-Logik, die diese Streams parallel abfeuert und die Ergebnisse aggregiert.
3. **Integration:** Nutze die `EdgeRegistry` (aus WP-22) für die Boosts in jedem Stream.
Bitte bestätige die Übernahme dieser "Agentic Architecture" (WP-25).
+123
View File
@@ -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]
```
+267
View File
@@ -0,0 +1,267 @@
# Release Notes: Mindnet v2.9.3 (WP15c)
**Release Date:** 2025-12-31
**Type:** Feature Release - Multigraph & Diversity Engine
**Branch:** WP15c
---
## 🎯 Übersicht
Diese Version transformiert den Graphen von einer flachen Struktur zu einem **hochpräzisen Multigraphen** mit intelligenter Ergebnis-Filterung (Diversity) und gewichtetem Scoring. Die Änderungen verbessern die Retrieval-Qualität durch präzise Sektions-Links, Note-Level Diversity Pooling und mathematische Super-Edge Aggregation.
---
## ✨ Neue Features
### Section-Präzision & Multigraph-Modus
Mindnet erkennt nun präzise **Obsidian-Anker** (`[[Note#Section]]`) und **Self-Links** (`[[#Section]]`):
**Obsidian-Anker:**
```markdown
[[rel:based_on Mein Leitbild#P3 – Disziplin]]
```
**Self-Links:**
```markdown
[[#P3 – Disziplin]] → Verlinkt innerhalb derselben Note
```
**Technische Details:**
- Links werden in `target_id="Note"` und `target_section="Section"` aufgelöst
- Edge-IDs enthalten `variant` (Section) für eindeutige Identifikation
- **Multigraph-Modus:** Mehrere Kanten zwischen denselben Notizen möglich, wenn sie auf verschiedene Sections zeigen
- Verhindert "Phantom-Knoten" durch korrekte Trennung von Note-Name und Abschnitt
### Provenance Firewall (Edge Registry v0.8.0)
Die **Edge Registry** stellt sicher, dass System-Kanten (`next`, `prev`, `belongs_to`) ausschließlich durch interne Struktur-Prozesse und nicht durch Nutzer oder KI manipuliert werden können:
**Schutz-Mechanismus:**
- System-Kanten 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
**Vorteil:** Garantiert Graph-Integrität und verhindert Manipulationen an der internen Struktur.
### Note-Level Diversity Pooling
Um das **"Note-Flooding"** (Dominanz einer einzigen Notiz durch viele ähnliche Chunks) zu verhindern, wird pro `note_id` nur noch der relevanteste Treffer im Endergebnis behalten:
**Workflow:**
1. Alle Kandidaten werden nach finalem Score sortiert
2. Pro `note_id` wird nur der Hit mit dem höchsten `total_score` behalten
3. Begrenzung auf `top_k` nach dem Diversity-Pooling
**Impact:** Verhindert, dass 10 Chunks derselben Note andere KeyNotes verdrängen. Erhöht die Vielfalt der Suchergebnisse.
### Super-Edge Aggregation
Parallele Kanten zwischen zwei Notizen werden mathematisch zu einer **"Super-Edge"** aggregiert:
**Aggregations-Logik:**
- Primäre Kante (höchstes Gewicht) zählt voll
- Jede weitere Kante (z.B. auf eine andere Sektion) wird mit Dämpfungsfaktor **0.1** gewichtet
- Formel: `total_weight = primary_weight + sum(secondary_weights * 0.1)`
**Vorteil:** Verhindert Score-Explosionen durch multiple Links auf verschiedene Sections derselben Note.
**Metadaten:**
- `is_super_edge`: Flag für Explanation Layer
- `edge_count`: Anzahl der aggregierten Kanten
---
## 🔧 Verbesserungen
### Mathematisches Scoring (WP-22 Integration)
Die Engine berechnet den finalen Score basierend auf einer **hybriden Multiplikations-Formel**:
```
Final = (Semantic * StatusMult) * (1 + TypeBoost + EdgeBonus + CentBonus)
```
**Komponenten:**
- **Base Score:** `Semantic * StatusMult` (Lifecycle-Filter)
- **Status-Gatekeeper:** `stable` = 1.2, `draft` = 0.5, `active` = 1.0
- **Boosts:** `TypeBoost + EdgeBonus + CentBonus` (additiv, dann multiplikativ auf Base)
- **Graph Boost Factor:** Intent-spezifische Verstärkung (1.5x bei aktivem Intent)
**Vorteil:** Status wirkt als Multiplikator auf die Basis-Relevanz, Graph-Boni werden proportional verstärkt.
### Explanation Layer
Der Retriever liefert detaillierte Begründungen für jeden Bonus:
- Sektions-Links (z.B. "Link zu 'Mein Leitbild#P3 – Disziplin'")
- Hub-Zentralität (z.B. "Note ist zentraler Knoten mit 5 eingehenden Kanten")
- Super-Edge-Informationen (z.B. "3 parallele Kanten aggregiert")
- Provenance-Informationen (z.B. "Explizite Kante vom Nutzer")
**Impact:** Massiv erhöhte Transparenz für Debugging und Nutzer-Vertrauen.
### Metadaten-Persistenz
Der In-Memory Subgraph und der Datenbank-Adapter wurden so erweitert, dass Metadaten durchgängig erhalten bleiben:
**Erhaltene Metadaten:**
- `target_section`: Abschnitts-Name für präzise Verlinkung
- `provenance`: Herkunft der Kante (explicit, smart, rule, structure)
- `confidence`: Vertrauenswürdigkeit (0.0 - 1.0)
- `is_super_edge`: Flag für aggregierte Kanten
**Vorteil:** Ermöglicht präzises Retrieval-Reasoning und Explanation Layer.
### Profil-Synchronisation (Ingestion v2.13.12)
Der Ingestion-Prozessor löst Chunking-Profile hierarchisch über die `types.yaml` auf:
**Hierarchie:**
1. **Frontmatter** (höchste Priorität)
2. **types.yaml Typ-Config**
3. **Global Defaults**
**Impact:** Konsistente Verarbeitung je nach Notiz-Typ. Note-Typen wie `value` erhalten automatisch das korrekte Profil (`structured_smart_edges_strict`).
---
## 🐛 Bugfixes
- ✅ **Behoben:** "Phantom-Knoten" durch korrekte Trennung von Note-Name und Section in `target_id`
- ✅ **Behoben:** Score-Explosionen durch multiple Links auf verschiedene Sections
- ✅ **Behoben:** "Note-Flooding" durch fehlende Diversity-Filterung
- ✅ **Behoben:** Inkonsistente Metadaten durch fehlende Persistenz im Subgraph
- ✅ **Behoben:** Manipulation von System-Kanten durch Provenance Firewall
---
## ⚠️ Breaking Changes & Migration
### 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
```
**Was passiert beim Re-Import?**
- Bestehende Links werden neu geparst und in `target_id` + `target_section` aufgeteilt
- Self-Links (`[[#Section]]`) werden korrekt aufgelöst
- Edge-Struktur wird konsolidiert (Multigraph-Support)
---
## 📚 API-Änderungen
### Keine Breaking Changes
Die API bleibt vollständig kompatibel. Neue Metadaten werden optional zurückgegeben:
**EdgeDTO (erweitert):**
```python
class EdgeDTO(BaseModel):
# ... bestehende Felder ...
target_section: Optional[str] = None # Neu: Abschnitts-Name
is_super_edge: Optional[bool] = False # Neu: Aggregations-Flag
```
**QueryResponse (erweitert):**
- Explanation Layer enthält nun Super-Edge-Informationen
- Metadaten wie `target_section` werden in Edge-Objekten zurückgegeben
---
## 📖 Dokumentation
Alle relevanten Dokumente wurden 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)
---
## 🔄 Technische Details
### Geänderte Module
**Graph Topology:**
- `app/services/edge_registry.py`: Provenance Firewall (v0.8.0)
- `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)
**Retrieval:**
- `app/core/retrieval/retriever.py`: Note-Level Diversity Pooling, Super-Edge Aggregation (v0.7.0)
- `app/core/retrieval/retriever_scoring.py`: Hybrid Scoring Formula (v1.0.3)
**Ingestion:**
- `app/core/ingestion/ingestion_processor.py`: Registry-First Profiling (v2.13.12)
### Versionsnummern
- 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**
---
## 🚀 Upgrade-Pfad
### Für Administratoren
1. **Code aktualisieren:**
```bash
git pull origin main
source .venv/bin/activate
pip install -r requirements.txt
```
2. **Services neu starten:**
```bash
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod
```
3. **Optional: Re-Import für optimale Nutzung:**
```bash
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
```
### Für Entwickler
- Keine Code-Änderungen erforderlich, wenn nur API genutzt wird
- Frontend kann neue Metadaten (`target_section`, `is_super_edge`) optional nutzen
- Explanation Layer enthält nun Super-Edge-Informationen
---
## 📝 Bekannte Einschränkungen
- **Re-Import-Dauer:** Große Vaults (>10.000 Notizen) können 30+ Minuten benötigen (optional)
- **Temporärer Speicher:** Während des Re-Imports kann Qdrant-Speicher temporär ansteigen
---
## 🙏 Danksagungen
Diese Version wurde durch umfangreiche Code-Analyse und Dokumentationsprüfung ermöglicht. Besonderer Fokus lag auf:
- Transformation zu einem hochpräzisen Multigraphen
- Intelligente Ergebnis-Filterung (Diversity Engine)
- Mathematisches Scoring mit gewichteten Boni
- Graph-Integrität durch Provenance Firewall
---
**Vollständige Changelog:** Siehe Git-Commits für detaillierte Änderungen
**Support:** Bei Fragen siehe [Admin Operations Guide](../04_Operations/04_admin_operations.md)
+138
View File
@@ -0,0 +1,138 @@
# Branch Merge Commit Message: WP25
```
feat: Agentic Multi-Stream RAG Orchestration (v3.0)
## Architektur-Transformation (WP-25)
### Agentic Multi-Stream RAG Orchestration
- Übergang von linearer RAG-Architektur zu paralleler Multi-Stream Engine
- Parallele Abfragen in spezialisierten Wissens-Streams (Values, Facts, Biography, Risk, Tech)
- Stream-Tracing: Jeder Treffer wird mit `stream_origin` markiert
- Fehler-Resilienz: Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage
**Geänderte Dateien:**
- `app/core/retrieval/decision_engine.py`: Multi-Stream Orchestrator (v1.0.3)
- `app/routers/chat.py`: Hybrid Router Integration (v3.0.2)
- `app/models/dto.py`: Stream-Tracing Support (v0.7.1)
### Intent-basiertes Routing ("The Brain")
- Hybrid-Modus: Keyword Fast-Path + LLM Slow-Path
- Strategien: FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW
- Sofortige Erkennung von Triggern wie "Soll ich" oder "Wann" ohne LLM-Call
- Komplexe semantische Analyse für unklare Anfragen
**Geänderte Dateien:**
- `app/routers/chat.py`: Hybrid Router mit Keyword-Fast-Path (v3.0.2)
- `app/core/retrieval/decision_engine.py`: LLM-basiertes Routing (v1.0.3)
### Wissens-Synthese
- Spezialisierte Templates in `prompts.yaml` mit expliziten Stream-Variablen
- Pre-Initialization aller Stream-Variablen (verhindert KeyErrors)
- Provider-spezifische Templates für Ollama, Gemini und OpenRouter
- Differenzierte Abwägung zwischen Fakten und persönlichen Werten
**Geänderte Dateien:**
- `config/prompts.yaml`: Stream-Templates (v3.1.2)
- `app/core/retrieval/decision_engine.py`: Synthese-Logik (v1.0.3)
## Stream-Konfiguration & Typ-Synchronisation
### Stream-Library (decision_engine.yaml v3.1.6)
- **Values Stream:** Identität, Ethik und Prinzipien (filter_types: value, principle, belief, etc.)
- **Facts Stream:** Operative Daten (filter_types: project, decision, task, etc.)
- **Biography Stream:** Persönliche Erfahrungen (filter_types: experience, journal, profile)
- **Risk Stream:** Hindernisse und Gefahren (filter_types: risk, obstacle, bias)
- **Tech Stream:** Technisches Wissen (filter_types: concept, source, glossary, etc.)
**Edge-Boosts pro Stream:**
- Values: `guides: 3.0`, `enforced_by: 2.5`, `based_on: 2.0`
- Facts: `part_of: 2.0`, `depends_on: 1.5`, `implemented_in: 1.5`
- Risk: `blocks: 2.5`, `impacts: 2.0`, `risk_of: 2.5`
**Geänderte Dateien:**
- `config/decision_engine.yaml`: Multi-Stream Konfiguration (v3.1.6)
## Bugfixes & Optimierungen
### Vault-Import Performance
- "Empty Response Guard" korrigiert: Kurze Ingest-Antworten (YES/NO) lösen nicht mehr fälschlicherweise langsame Fallbacks aus
- Entfernung des <5-Zeichen Guards ermöglicht YES/NO Validierungen
**Geänderte Dateien:**
- `app/services/llm_service.py`: Ingest-Stability Patch (v3.4.2)
### Cloud-Resilienz
- Sicherheitscheck für das `choices`-Array in `_execute_openrouter` implementiert
- Verhindert JSON-Errors bei überlasteten APIs
**Geänderte Dateien:**
- `app/services/llm_service.py`: Empty Response Guard (v3.4.2)
### Template-Robustheit
- Automatische Vor-Initialisierung aller Stream-Variablen in der `DecisionEngine`
- Verhindert `KeyError`-Abstürze bei unvollständigen Konfigurationen
- Fallback-Mechanismus bei Template-Fehlern
**Geänderte Dateien:**
- `app/core/retrieval/decision_engine.py`: Pre-Initialization (v1.0.3)
### Intent-Kollision
- Generische Begriffe (wie "Projekt") wurden aus den Keyword-Triggern entfernt
- Sicherstellt, dass strategische Fragen (z.B. "Soll ich...?") korrekt als `DECISION` geroutet werden
**Geänderte Dateien:**
- `config/decision_engine.yaml`: Keyword-Fix (v3.1.6)
## Ollama Context-Throttling
- Vor der Übergabe an Ollama prüft der Chat-Router, ob der Kontext die Grenze von `MAX_OLLAMA_CHARS` überschreitet (Standard: 10.000)
- Automatische Kürzung bei großen Kontexten
**Geänderte Dateien:**
- `app/routers/chat.py`: Context-Throttling (v3.0.2)
## Lifespan Management
- FastAPI-Anwendung implementiert Lifespan-Management für sauberen Startup und Shutdown
- Integritäts-Check der WP-25 Konfiguration beim Startup
- Ressourcen-Cleanup beim Shutdown
- Globale Fehlerbehandlung für asynchrone Prozesse
**Geänderte Dateien:**
- `app/main.py`: Lifespan Management (v1.0.0)
## Impact & Breaking Changes
### Keine Migration erforderlich
**WICHTIG:** Diese Version ist **rückwärtskompatibel**. Bestehende Vaults funktionieren ohne Re-Import.
**Konfigurations-Updates:**
- `decision_engine.yaml` wurde auf v3.1.6 aktualisiert (Multi-Stream Struktur)
- `prompts.yaml` wurde auf v3.1.2 aktualisiert (Stream-Templates)
- **Empfehlung:** Backup der alten Konfigurationsdateien vor dem Update
### API-Erweiterungen
- `QueryHit.stream_origin`: Name des Ursprungs-Streams (optional)
- `ChatResponse.intent`: Die gewählte WP-25 Strategie (optional)
- `ChatResponse.intent_source`: Quelle der Intent-Erkennung (optional)
## Dokumentation
Alle relevanten Dokumente aktualisiert:
- `03_tech_chat_backend.md`: Agentic Multi-Stream RAG, Intent-basiertes Routing, Wissens-Synthese
- `03_tech_configuration.md`: decision_engine.yaml, prompts.yaml (Stream-Struktur)
- `03_tech_api_reference.md`: Erweiterte DTOs (stream_origin, intent)
## Versionen
- Decision Engine: v1.0.3
- Chat Router: v3.0.2
- LLM Service: v3.4.2
- DTOs: v0.7.1
- Main: v1.0.0
- decision_engine.yaml: v3.1.6
- prompts.yaml: v3.1.2
Closes #[issue-number]
```
+268
View File
@@ -0,0 +1,268 @@
# Release Notes: Mindnet v3.0.0 (WP25)
**Release Date:** 2026-01-01
**Type:** Feature Release - Agentic Multi-Stream RAG Orchestration
**Branch:** WP25
---
## 🎯 Übersicht
Diese Version markiert den Übergang von Mindnet von einer klassischen, linearen RAG-Architektur zu einer **Agentic Multi-Stream Engine**. Das System agiert nun als intelligenter Orchestrator, der Nutzeranfragen analysiert, in parallele Wissens-Streams aufteilt und diese zu einer kontextreichen, wertebasierten Antwort synthetisiert.
---
## ✨ Neue Features
### Agentic Multi-Stream RAG Orchestration
Mindnet führt nun **parallele Abfragen** in spezialisierten Wissens-Streams aus, anstatt einer einzelnen Suche:
**Stream-Library:**
* **Values Stream:** Extrahiert Identität, Ethik und Prinzipien (`value`, `principle`, `belief`, `trait`, `boundary`, `need`, `motivation`).
* **Facts Stream:** Liefert operative Daten zu Projekten, Tasks und Status (`project`, `decision`, `task`, `goal`, `event`, `state`).
* **Biography Stream:** Greift auf persönliche Erfahrungen und Journal-Einträge zu (`experience`, `journal`, `profile`, `person`).
* **Risk Stream:** Identifiziert Hindernisse und potenzielle Gefahren (`risk`, `obstacle`, `bias`).
* **Tech Stream:** Bündelt technisches Wissen, Code und Dokumentation (`concept`, `source`, `glossary`, `idea`, `insight`, `skill`, `habit`).
**Vorteile:**
* **Präzise Kontext-Ladung:** Jeder Stream fokussiert auf spezifische Wissensbereiche.
* **Parallele Ausführung:** Alle Streams werden gleichzeitig abgefragt (asyncio.gather).
* **Stream-Tracing:** Jeder Treffer wird mit `stream_origin` markiert für Feedback-Optimierung.
* **Fehler-Resilienz:** Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage.
### Intent-basiertes Routing ("The Brain")
Der Router wurde zu einem **hybriden System** erweitert, das Anfragen klassifiziert, bevor die Suche beginnt:
**Strategien:**
* **FACT_WHAT:** Wissen/Listen (z.B. "Was ist...", "Welche sind...").
* **FACT_WHEN:** Zeitpunkte (z.B. "Wann...", "Datum...").
* **DECISION:** Beratung (z.B. "Soll ich...", "Sollte ich...", "Empfehlung...").
* **EMPATHY:** Reflexion (z.B. "Fühle...", "Stress...", "Angst...").
* **CODING:** Technik (z.B. "Code...", "Python...", "Bug...").
* **INTERVIEW:** Datenerfassung (z.B. "Neues Projekt...", "Erfahrung...").
**Hybrid-Modus:**
* **Keyword Fast-Path:** Sofortige Erkennung von Triggern wie "Soll ich" oder "Wann" ohne LLM-Call.
* **LLM Slow-Path:** Komplexe semantische Analyse für unklare Anfragen.
* **Type Keywords:** Automatische Erkennung von Objekt-Typen für Interview-Modus.
**Vorteil:** Reduziert Latenz durch schnelle Keyword-Erkennung, nutzt LLM nur bei Bedarf.
### Wissens-Synthese
Die Zusammenführung der Daten erfolgt über spezialisierte Templates in der `prompts.yaml`:
**Template-Struktur:**
* Explizite Variablen für jeden Stream (z.B. `{values_stream}`, `{risk_stream}`).
* **Pre-Initialization:** Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors).
* **Provider-spezifische Templates:** Separate Versionen für Ollama, Gemini und OpenRouter.
**Synthese-Strategien:**
* **FACT_WHAT/FACT_WHEN:** Kombiniert Fakten, Biographie und Technik.
* **DECISION:** Wägt Fakten gegen Werte ab, evaluiert Risiken.
* **EMPATHY:** Fokus auf Biographie und Werte.
* **CODING:** Technik und Fakten.
**Vorteil:** Ermöglicht dem LLM eine differenzierte Abwägung zwischen Fakten und persönlichen Werten.
---
## 🔧 Verbesserungen
### Stream-Konfiguration & Typ-Synchronisation
Jeder Stream nutzt individuelle **Edge-Boosts** und **Filter-Types**, die strikt mit der `types.yaml` (v2.7.0) synchronisiert sind:
**Beispiele:**
* **Values Stream:** `guides: 3.0`, `enforced_by: 2.5`, `based_on: 2.0`.
* **Facts Stream:** `part_of: 2.0`, `depends_on: 1.5`, `implemented_in: 1.5`.
* **Risk Stream:** `blocks: 2.5`, `impacts: 2.0`, `risk_of: 2.5`.
**Vorteil:** Präzise Gewichtung der Graph-Kanten je nach Wissensbereich.
### Template-Robustheit
**Pre-Initialization:** Automatische Vor-Initialisierung aller Stream-Variablen in der `DecisionEngine` verhindert `KeyError`-Abstürze bei unvollständigen Konfigurationen.
**Fallback-Mechanismus:** Bei Template-Fehlern wird ein vereinfachter Prompt mit allen verfügbaren Stream-Ergebnissen verwendet.
### Ollama Context-Throttling
Vor der Übergabe an Ollama prüft der Chat-Router, ob der Kontext (RAG-Hits) die Grenze von `MAX_OLLAMA_CHARS` überschreitet (Standard: 10.000) und kürzt diesen ggf.
**Vorteil:** Verhindert VRAM-Überlastung bei großen Kontexten.
---
## 🐛 Bugfixes
- ✅ **Behoben:** Vault-Import Performance - "Empty Response Guard" korrigiert, damit kurze Ingest-Antworten (YES/NO) nicht mehr fälschlicherweise langsame Fallbacks auslösen.
- ✅ **Behoben:** Cloud-Resilienz - Sicherheitscheck für das `choices`-Array in `_execute_openrouter` implementiert, um JSON-Errors bei überlasteten APIs zu verhindern.
- ✅ **Behoben:** Template-Robustheit - Automatische Vor-Initialisierung aller Stream-Variablen verhindert `KeyError`-Abstürze.
- ✅ **Behoben:** Intent-Kollision - Generische Begriffe (wie "Projekt") wurden aus den Keyword-Triggern entfernt, um sicherzustellen, dass strategische Fragen (z.B. "Soll ich...?") korrekt als `DECISION` geroutet werden.
---
## ⚠️ Breaking Changes & Migration
### Keine Migration erforderlich
**WICHTIG:** Diese Version ist **rückwärtskompatibel**. Bestehende Vaults funktionieren ohne Re-Import.
**Konfigurations-Updates:**
* `decision_engine.yaml` wurde auf v3.1.6 aktualisiert (Multi-Stream Struktur).
* `prompts.yaml` wurde auf v3.1.2 aktualisiert (Stream-Templates).
* **Empfehlung:** Backup der alten Konfigurationsdateien vor dem Update.
---
## 📚 API-Änderungen
### Erweiterte DTOs
**QueryHit (erweitert):**
```python
class QueryHit(BaseModel):
# ... bestehende Felder ...
stream_origin: Optional[str] = None # Neu: Name des Ursprungs-Streams
```
**ChatResponse (erweitert):**
```python
class ChatResponse(BaseModel):
# ... bestehende Felder ...
intent: Optional[str] = "FACT" # Neu: Die gewählte WP-25 Strategie
intent_source: Optional[str] = "LLM_Router" # Neu: Quelle der Intent-Erkennung
```
**Impact für API-Consumer:**
* Frontend kann `stream_origin` für visuelle Kennzeichnung der Quellen nutzen.
* `intent` und `intent_source` ermöglichen Debugging und Analytics.
---
## 📖 Dokumentation
Alle relevanten Dokumente wurden aktualisiert:
- ✅ `03_tech_chat_backend.md`: Agentic Multi-Stream RAG, Intent-basiertes Routing, Wissens-Synthese
- ✅ `03_tech_configuration.md`: decision_engine.yaml, prompts.yaml (Stream-Struktur)
- ✅ `03_tech_api_reference.md`: Erweiterte DTOs (stream_origin, intent)
---
## 🔄 Technische Details
### Geänderte Module
**Decision Engine:**
- `app/core/retrieval/decision_engine.py`: Multi-Stream Orchestrator (v1.0.3)
- Paralleles Retrieval via `_execute_parallel_streams()`
- Stream-Tracing mit `stream_origin`
- Pre-Initialization der Stream-Variablen
**Chat Router:**
- `app/routers/chat.py`: Hybrid Router Integration (v3.0.2)
- Keyword Fast-Path + LLM Slow-Path
- Multi-Stream Orchestrierung
- Ollama Context-Throttling
**LLM Service:**
- `app/services/llm_service.py`: Ingest-Stability Patch (v3.4.2)
- Entfernung des <5-Zeichen Guards
- Empty Response Guard für OpenRouter
- Lazy Initialization der DecisionEngine
**DTOs:**
- `app/models/dto.py`: Stream-Tracing Support (v0.7.1)
- `stream_origin` in `QueryHit`
- `intent` und `intent_source` in `ChatResponse`
**Main:**
- `app/main.py`: Lifespan Management (v1.0.0)
- Startup-Integritäts-Check
- Ressourcen-Cleanup beim Shutdown
- Globale Fehlerbehandlung
**Konfiguration:**
- `config/decision_engine.yaml`: Multi-Stream Konfiguration (v3.1.6)
- `config/prompts.yaml`: Stream-Templates (v3.1.2)
### Versionsnummern
- Decision Engine: **v1.0.3**
- Chat Router: **v3.0.2**
- LLM Service: **v3.4.2**
- DTOs: **v0.7.1**
- Main: **v1.0.0**
- decision_engine.yaml: **v3.1.6**
- prompts.yaml: **v3.1.2**
---
## 🚀 Upgrade-Pfad
### Für Administratoren
1. **Code aktualisieren:**
```bash
git pull origin main
source .venv/bin/activate
pip install -r requirements.txt
```
2. **Konfiguration prüfen:**
```bash
# Backup der alten Konfigurationen
cp config/decision_engine.yaml config/decision_engine.yaml.backup
cp config/prompts.yaml config/prompts.yaml.backup
# Prüfen, ob neue Konfigurationen vorhanden sind
ls -la config/decision_engine.yaml config/prompts.yaml
```
3. **Services neu starten:**
```bash
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod
```
### Für Entwickler
- Keine Code-Änderungen erforderlich, wenn nur API genutzt wird
- Frontend kann neue Felder (`stream_origin`, `intent`, `intent_source`) optional nutzen
- Stream-Tracing ermöglicht Feedback-Optimierung pro Wissensbereich
---
## 📝 Bekannte Einschränkungen
- **Stream-Parallelität:** Maximale Anzahl paralleler Streams ist durch asyncio-Limits begrenzt (typischerweise 5-10 Streams).
- **Kontext-Größe:** Große Kontexte (>10.000 Zeichen) werden bei Ollama automatisch gekürzt.
---
## 🔮 Ausblick (WP-25a: Agentic Refinement)
Auf Basis des stabilen WP-25 Fundaments sind folgende Erweiterungen geplant:
* **Pre-Synthesis:** LLM-basierte Komprimierung überlanger Streams vor der finalen Antwortgenerierung.
* **Kontext-Budgeting:** Intelligente Verteilung der verfügbaren Token auf die aktivierten Streams.
* **Stream-specific Provider:** Zuweisung unterschiedlicher KI-Modelle pro Wissensbereich (z.B. lokales Ollama für Identitäts-Werte, Gemini für technische Fakten).
---
## 🙏 Danksagungen
Diese Version wurde durch umfangreiche Architektur-Überarbeitung ermöglicht. Besonderer Fokus lag auf:
- Transformation zu einer Agentic Multi-Stream Engine
- Intelligente Intent-Erkennung mit Hybrid-Routing
- Parallele Wissens-Synthese mit wertebasierter Abwägung
- Robustheit und Fehler-Resilienz
---
**Vollständige Changelog:** Siehe Git-Commits für detaillierte Änderungen
**Support:** Bei Fragen siehe [Admin Operations Guide](../04_Operations/04_admin_operations.md)
+103
View File
@@ -0,0 +1,103 @@
# Branch Merge Commit: WP-25a
**Branch:** `WP25a`
**Target:** `main`
**Version:** v3.1.0
**Date:** 2026-01-02
---
## Commit Message
```
feat: Mixture of Experts (MoE) & Fallback-Kaskade (v3.0.0)
### Mixture of Experts (MoE) Architektur
- Übergang von provider-basierter zu profilbasierter Experten-Steuerung
- Zentrale Experten-Registry (`llm_profiles.yaml` v1.3.0)
- Aufgabenspezifische Profile: synthesis_pro, tech_expert, compression_fast, ingest_validator, identity_safe, embedding_expert
- Hardware-Optimierung: Lokaler Anker (Ollama/Phi-3) für maximale Privacy
### Rekursive Fallback-Kaskade
- Implementierung in `app/services/llm_service.py` (v3.5.2)
- Automatische Fallback-Logik bei Provider-Fehlern
- Schutz gegen Zirkel-Referenzen via `visited_profiles`-Tracking
- Background-Semaphore für parallele Tasks
### Pre-Synthesis Kompression (Module A)
- Asynchrone Verdichtung überlanger Wissens-Streams
- Konfigurierbare Schwellenwerte pro Stream (`compression_threshold`)
- Profil-gesteuerte Kompression via `compression_profile`
- Parallelisierung über `asyncio.gather()`
### Profilgesteuerte Ingestion
- Semantische Kanten-Validierung via `ingest_validator` (Temperature 0.0)
- Embedding-Konsolidierung über `embedding_expert` Profil
- Entfernung der Embedding-Konfiguration aus `.env`
### Startup-Schutz & Audit-Fixes
- Validierung von `llm_profiles.yaml` und `decision_engine.yaml` beim Booten
- Behebung der Sicherheitslücke in `DecisionEngine` (Fallback-Aufrufe nutzen nun `profile_name`)
- Circular Import Fix: Ingestion-Module nutzen neutrale `app.core.registry`
### Code-Komponenten
- `app/services/llm_service.py`: v3.5.2 (Rekursive Fallback-Kaskade)
- `app/core/retrieval/decision_engine.py`: v1.2.1 (Profile-Driven Orchestration)
- `app/core/ingestion/ingestion_processor.py`: v2.14.0 (Profilgesteuerte Validierung)
- `app/core/ingestion/ingestion_validation.py`: v2.13.0 (MoE-Profil Integration)
- `app/services/embeddings_client.py`: v2.6.0 (Profil-basierte Modell-Auflösung)
- `app/main.py`: v1.1.0 (Startup-Validierung)
### Konfiguration
- `config/llm_profiles.yaml`: v1.3.0 (Zentrale Experten-Registry)
- `config/decision_engine.yaml`: v3.2.2 (Decoupled MoE Logic, compression_thresholds)
### Dokumentation
- `03_tech_configuration.md`: llm_profiles.yaml Dokumentation
- `03_tech_chat_backend.md`: MoE Architektur und Fallback-Kaskade
- `02_concept_ai_personality.md`: Mixture of Experts Konzept
- `03_tech_ingestion_pipeline.md`: Profilgesteuerte Validierung
- `00_glossary.md`: Neue Begriffe (MoE, Profile, Fallback-Kaskade)
- `05_developer_guide.md`: Teach-the-AI mit Profilen
- `04_admin_operations.md`: Konfigurations-Updates
- `06_active_roadmap.md`: WP25a als abgeschlossen markiert
### Breaking Changes
- Keine Breaking Changes für Endbenutzer
- ENV-Variablen `MINDNET_LLM_PROVIDER`, `MINDNET_LLM_MODEL` etc. dienen nur noch als Fallback
- Neue Konfigurationsdatei `llm_profiles.yaml` ist erforderlich (Startup-Validierung)
### Migration
- Administratoren müssen `config/llm_profiles.yaml` erstellen
- System startet nicht, wenn `llm_profiles.yaml` fehlt oder ungültig ist
- ENV-Variablen bleiben als Fallback erhalten
---
**Status:** ✅ WP-25a ist zu 100% implementiert und audit-geprüft.
**Nächster Schritt:** WP-25b (Prompt-Orchestration & Model-Specific Tuning).
```
---
## Zusammenfassung
Dieser Merge führt die **Mixture of Experts (MoE) Architektur** in MindNet ein. Das System nutzt nun eine profilbasierte Experten-Steuerung statt einer globalen Provider-Konfiguration. Jede Systemaufgabe wird einem dedizierten Profil zugewiesen, das Modell, Provider und Parameter unabhängig definiert.
**Kern-Features:**
- Zentrale Experten-Registry (`llm_profiles.yaml`)
- Rekursive Fallback-Kaskade mit Schutz gegen Zirkel-Referenzen
- Pre-Synthesis Kompression für überlange Wissens-Streams
- Profilgesteuerte Ingestion mit deterministischer Validierung
- Startup-Schutz und Audit-Fixes
**Technische Integrität:**
- Alle LLM-Aufrufe nutzen nun die Profilsteuerung
- Startup-Validierung verhindert fehlerhafte Konfigurationen
- Circular Import Fix verbessert Wartbarkeit
**Dokumentation:**
- Vollständige Aktualisierung aller relevanten Dokumente
- Neue Begriffe im Glossar
- Konfigurations-Referenz erweitert
- Developer Guide aktualisiert
+186
View File
@@ -0,0 +1,186 @@
# MindNet v3.0.0 - Release Notes: WP-25a
**Release Date:** 2026-01-02
**Type:** Feature Release - Mixture of Experts (MoE) & Fallback-Kaskade
**Version:** 3.1.0 (WP-25a)
---
## 🎯 Überblick
Mit WP-25a wurde MindNet von einer provider-basierten Steuerung auf eine **profilbasierte Experten-Architektur (Mixture of Experts)** umgestellt. Jede Systemaufgabe (Synthese, Ingestion-Validierung, Routing, Kompression) wird nun einem dedizierten Profil zugewiesen, das Modell, Provider und Parameter unabhängig von der globalen Konfiguration definiert.
Diese Version markiert einen fundamentalen Architektur-Sprung: Von einer monolithischen LLM-Konfiguration hin zu einer modularen, aufgabenspezifischen Experten-Steuerung mit automatischer Resilienz.
---
## ✨ Neue Features
### 1. Mixture of Experts (MoE) Architektur
**Zentrale Experten-Steuerung (`llm_profiles.yaml` v1.3.0):**
* Einführung von Experten-Profilen für spezifische Aufgaben:
* `synthesis_pro`: Hochwertige Synthese für Chat-Antworten
* `tech_expert`: Fachspezialist für Code & Technik (Claude 3.5 Sonnet)
* `compression_fast`: Schnelle Kompression & Routing (Mistral 7B)
* `ingest_validator`: Deterministische Validierung (Temperature 0.0)
* `identity_safe`: Lokaler Anker (Ollama/Phi-3) für maximale Privacy
* `embedding_expert`: Zentrale Steuerung des Embedding-Modells
**Vorteile:**
* **Aufgabenspezifische Optimierung:** Jede Aufgabe nutzt das optimale Modell
* **Hardware-Optimierung:** Lokaler Anker für kleine Hardware-Umgebungen
* **Wartbarkeit:** Zentrale Konfiguration statt verstreuter ENV-Variablen
### 2. Rekursive Fallback-Kaskade
**Implementierung (`app/services/llm_service.py` v3.5.2):**
* Automatische Fallback-Logik bei Provider-Fehlern:
1. Versucht primäres Profil (z.B. `synthesis_pro`)
2. Bei Fehler → `fallback_profile` (z.B. `synthesis_backup`)
3. Bei weiterem Fehler → nächster Fallback (z.B. `identity_safe`)
4. Terminaler Endpunkt: `identity_safe` hat keinen Fallback (lokales Modell)
**Schutzmechanismen:**
* **Zirkuläre Referenzen:** `visited_profiles`-Tracking verhindert Endlosschleifen
* **Background-Semaphore:** Parallele Tasks werden gedrosselt (konfigurierbar via `BACKGROUND_LIMIT`)
### 3. Pre-Synthesis Kompression (Module A)
**Implementierung (`app/core/retrieval/decision_engine.py` v1.2.1):**
* Wissens-Streams, die den Schwellenwert (`compression_threshold`) überschreiten, werden **asynchron verdichtet**, bevor sie die Synthese erreichen
* **Konfigurierbar pro Stream:** Z.B. 2500 Zeichen für Values Stream, 3500 für Facts Stream
* **Profil-gesteuert:** Nutzt `compression_profile` (z.B. `compression_fast` für schnelle Zusammenfassung)
* **Parallelisierung:** Mehrere Streams können gleichzeitig komprimiert werden
**Vorteile:**
* Reduziert Token-Verbrauch bei langen Streams
* Beschleunigt Synthese durch kürzere Kontexte
* Erhält Relevanz durch intelligente Zusammenfassung
### 4. Profilgesteuerte Ingestion (Wissens-Gatekeeper)
**Implementierung:**
* `app/core/ingestion/ingestion_processor.py` v2.14.0
* `app/core/ingestion/ingestion_validation.py` v2.13.0
**Features:**
* Semantische Kanten-Validierung erfolgt zwingend über das MoE-Profil `ingest_validator` (Temperature 0.0 für Determinismus)
* **Embedding-Konsolidierung:** Der `EmbeddingsClient` (v2.6.0) bezieht Modellvorgaben und Dimensionen direkt aus dem Profil `embedding_expert`
* Entfernung der Embedding-Konfiguration aus der `.env` zugunsten zentraler Profil-Registry
### 5. Startup-Schutz & Audit-Fixes
**Implementierung (`app/main.py` v1.1.0):**
* Verifiziert beim Booten die Existenz und Validität von `llm_profiles.yaml` und `decision_engine.yaml`
* **Audit-Fix:** Behebung einer Sicherheitslücke in der `DecisionEngine`, durch die Fallback-Aufrufe bei Template-Fehlern die Profilsteuerung umgangen hätten
* **Circular Import Fix:** Ingestion-Module nutzen nun die neutrale `app.core.registry` für Text-Bereinigung und Registry-Lookups
---
## 🔧 Technische Änderungen
### Konfigurationsdateien
**Neue Datei:**
* `config/llm_profiles.yaml` v1.3.0: Zentrale Experten-Registry
**Aktualisierte Dateien:**
* `config/decision_engine.yaml` v3.2.2: Decoupled MoE Logic, Integration von `compression_thresholds`
### Code-Komponenten
| Komponente | Version | Änderungen |
| :--- | :--- | :--- |
| `app/services/llm_service.py` | v3.5.2 | Rekursive Fallback-Kaskade, Profil-Auflösung |
| `app/core/retrieval/decision_engine.py` | v1.2.1 | Profile-Driven Orchestration, Pre-Synthesis Kompression |
| `app/core/ingestion/ingestion_processor.py` | v2.14.0 | Profilgesteuerte Validierung |
| `app/core/ingestion/ingestion_validation.py` | v2.13.0 | MoE-Profil `ingest_validator` |
| `app/services/embeddings_client.py` | v2.6.0 | Profil-basierte Modell-Auflösung |
| `app/main.py` | v1.1.0 | Startup-Validierung der YAML-Dateien |
### Environment-Variablen
**Neue Variable:**
* `MINDNET_LLM_PROFILES_PATH`: Pfad zur Profil-Registry (Default: `config/llm_profiles.yaml`)
**Legacy (nur noch Fallback):**
* `MINDNET_LLM_PROVIDER`, `MINDNET_LLM_MODEL`, etc. dienen nur noch als Fallback, wenn kein Profil angegeben wird
---
## 🐛 Behobene Probleme
- ✅ **Behoben:** Sicherheitslücke in der `DecisionEngine` - Fallback-Aufrufe nutzen nun korrekt `profile_name`
- ✅ **Behoben:** Circular Import zwischen Ingestion-Modulen und Registry
- ✅ **Behoben:** Fehlende Startup-Validierung der YAML-Konfigurationen
---
## 📚 Dokumentation
**Aktualisierte Dokumente:**
- ✅ `03_tech_configuration.md`: llm_profiles.yaml Dokumentation
- ✅ `03_tech_chat_backend.md`: MoE Architektur und Fallback-Kaskade
- ✅ `02_concept_ai_personality.md`: Mixture of Experts Konzept
- ✅ `03_tech_ingestion_pipeline.md`: Profilgesteuerte Validierung
- ✅ `00_glossary.md`: Neue Begriffe (MoE, Profile, Fallback-Kaskade)
- ✅ `05_developer_guide.md`: Teach-the-AI mit Profilen
- ✅ `04_admin_operations.md`: Konfigurations-Updates
- ✅ `06_active_roadmap.md`: WP25a als abgeschlossen markiert
---
## 🚀 Migration & Upgrade
### Für Administratoren
1. **Neue Konfigurationsdatei erstellen:**
```bash
cp config/llm_profiles.yaml.example config/llm_profiles.yaml
# Anpassen nach Bedarf
```
2. **Startup-Validierung prüfen:**
```bash
# System startet nicht, wenn llm_profiles.yaml fehlt oder ungültig ist
python3 -m app.main
```
3. **ENV-Variablen (optional):**
Die `.env` Variablen `MINDNET_LLM_PROVIDER`, `MINDNET_LLM_MODEL` etc. dienen nur noch als Fallback. Die primäre Steuerung erfolgt über `llm_profiles.yaml`.
### Für Entwickler
**API-Änderungen:**
* `LLMService.generate_raw_response()` unterstützt nun `profile_name` Parameter
* Fallback-Kaskade erfolgt automatisch bei Fehlern
* `visited_profiles`-Tracking verhindert Zirkel-Referenzen
**Konfiguration:**
* Neue Profile können in `llm_profiles.yaml` definiert werden
* `decision_engine.yaml` referenziert Profile über `router_profile`, `llm_profile`, `compression_profile`
---
## 🔮 Ausblick (WP-25b: Prompt-Orchestration & Model-Specific Tuning)
- Pre-Synthesis: LLM-basierte Komprimierung überlanger Streams (✅ bereits implementiert)
- Kontext-Budgeting: Intelligente Token-Verteilung
- Stream-specific Provider: Unterschiedliche KI-Modelle pro Wissensbereich
- Prompt-Orchestration: Dynamische Prompt-Anpassung basierend auf Profil und Kontext
---
## 📊 Metriken & Performance
**Erwartete Verbesserungen:**
* **Resilienz:** Automatische Fallback-Kaskade reduziert Ausfallzeiten
* **Token-Effizienz:** Pre-Synthesis Kompression reduziert Token-Verbrauch bei langen Streams
* **Determinismus:** Profilgesteuerte Validierung (Temperature 0.0) erhöht Konsistenz
* **Wartbarkeit:** Zentrale Profil-Registry vereinfacht Konfigurations-Management
---
**Status:** ✅ WP-25a ist zu 100% implementiert und audit-geprüft.
**Nächster Schritt:** WP-25b (Prompt-Orchestration & Model-Specific Tuning).
+97
View File
@@ -0,0 +1,97 @@
# Branch Merge Commit: WP-25b
**Branch:** `WP25b`
**Target:** `main`
**Version:** v3.1.1
**Date:** 2026-01-02
---
## Commit Message
```
feat: Lazy-Prompt-Orchestration & Full Resilience (v3.1.1)
### Hierarchisches Prompt-Resolution-System
- Dreistufige Auflösungs-Logik: Level 1 (Modell-ID) → Level 2 (Provider) → Level 3 (Default)
- Modell-spezifische Optimierungen für Gemini 2.0, Llama 3.3, Qwen 2.5
- PROMPT-TRACE Logging für vollständige Transparenz
- Implementierung in `app/services/llm_service.py` (v3.5.5)
### Lazy-Prompt-Orchestration
- Prompts werden erst zur Laufzeit geladen, basierend auf aktivem Modell
- Parameter: `prompt_key` und `variables` statt vorformatierter Strings
- Maximale Resilienz bei Modell-Fallbacks (Cloud → Local)
- Vollständige Integration in Chat, Ingestion und DecisionEngine
### Ultra-robustes Intent-Parsing
- Regex-basierter Parser bereinigt Modell-Artefakte (z.B. `CODING[/S]` → `CODING`)
- Implementierung in `app/core/retrieval/decision_engine.py` (v1.3.2)
- Fehlerresistenz gegen Stop-Marker, Newlines oder Modell-Plaudereien
### Differenzierte Ingestion-Validierung
- Unterscheidung zwischen transienten (Netzwerk) und permanenten (Config) Fehlern
- Transiente Fehler erlauben Kante (Datenverlust vermeiden)
- Permanente Fehler lehnen Kante ab (Graph-Qualität schützen)
- Implementierung in `app/core/ingestion/ingestion_validation.py` (v2.14.0)
### Code-Komponenten
- `app/services/llm_service.py`: v3.5.5 (Hierarchische Prompt-Resolution, Lazy-Loading)
- `app/core/retrieval/decision_engine.py`: v1.3.2 (Ultra-robustes Intent-Parsing)
- `app/core/ingestion/ingestion_validation.py`: v2.14.0 (Lazy-Prompt-Integration)
- `app/routers/chat.py`: v3.0.3 (Lazy-Prompt-Loading für Chat-Synthese)
### Konfiguration
- `config/prompts.yaml`: v3.2.2 (Hierarchische Struktur mit Modell-spezifischen Overrides)
- 100% Erhalt der Original-Prompts aus v3.1.2 für Provider-Ebene
- Integration von Modell-spezifischen Overrides
- Hinzufügen von `compression_template`
### Dokumentation
- `03_tech_chat_backend.md`: Hierarchisches Prompt-Resolution-System
- `03_tech_configuration.md`: prompts.yaml hierarchische Struktur
- `02_concept_ai_personality.md`: Lazy-Prompt-Orchestration Konzept
- `03_tech_ingestion_pipeline.md`: Differenzierte Validierung
- `00_glossary.md`: Neue Begriffe (Lazy-Prompt, PROMPT-TRACE)
- `05_developer_guide.md`: Lazy-Prompt-Orchestration für Entwickler
- `06_active_roadmap.md`: WP25b als abgeschlossen markiert
### Breaking Changes
- Keine Breaking Changes für Endbenutzer
- Vorformatierte Prompts werden weiterhin unterstützt (Abwärtskompatibilität)
- Neue API-Parameter `prompt_key` und `variables` optional
### Migration
- Keine Migration erforderlich
- System funktioniert ohne Änderungen
- Optional: Modell-spezifische Prompts können in `prompts.yaml` definiert werden
---
**Status:** ✅ WP-25b ist zu 100% implementiert und audit-geprüft.
**Nächster Schritt:** WP-25c (Kontext-Budgeting & Erweiterte Prompt-Optimierung).
```
---
## Zusammenfassung
Dieser Merge führt die **Lazy-Prompt-Orchestration** in MindNet ein. Das System nutzt nun eine hierarchische Prompt-Auflösung mit Lazy-Loading, die Prompts erst zur Laufzeit lädt, basierend auf dem exakt aktiven Modell.
**Kern-Features:**
- Hierarchisches Prompt-Resolution-System (3-stufig)
- Lazy-Prompt-Orchestration mit modell-spezifischem Tuning
- Ultra-robustes Intent-Parsing via Regex
- Differenzierte Ingestion-Validierung
- PROMPT-TRACE Logging für vollständige Transparenz
**Technische Integrität:**
- Alle LLM-Aufrufe nutzen nun Lazy-Prompt-Loading
- Modell-Artefakte werden zuverlässig bereinigt
- Fehlerbehandlung differenziert zwischen transienten und permanenten Fehlern
**Dokumentation:**
- Vollständige Aktualisierung aller relevanten Dokumente
- Neue Begriffe im Glossar
- Konfigurations-Referenz erweitert
- Developer Guide aktualisiert
+205
View File
@@ -0,0 +1,205 @@
# MindNet v3.1.1 - Release Notes: WP-25b
**Release Date:** 2026-01-02
**Type:** Feature Release - Lazy-Prompt-Orchestration & Full Resilience
**Version:** 3.1.1 (WP-25b)
---
## 🎯 Überblick
Mit WP-25b wurde MindNet von statischer Prompt-Formatierung auf eine **hierarchische Lazy-Prompt-Orchestration** umgestellt. Prompts werden erst im Moment des Modellaustauschs geladen, basierend auf dem exakt aktiven Modell. Dies ermöglicht modell-spezifisches Tuning und maximale Resilienz bei Modell-Fallbacks.
Diese Version markiert einen weiteren Architektur-Sprung: Von vorformatierter Prompt-Strings hin zu einer dynamischen, modell-spezifischen Prompt-Auflösung mit vollständiger Traceability.
---
## ✨ Neue Features
### 1. Hierarchisches Prompt-Resolution-System
**Implementierung (`app/services/llm_service.py` v3.5.5):**
Dreistufige Auflösungs-Logik für maximale Präzision und Resilienz:
1. **Level 1 (Modell-ID):** Exakte Übereinstimmung für spezifische Modelle
* **Beispiel:** `google/gemini-2.0-flash-exp:free`, `meta-llama/llama-3.3-70b-instruct:free`
* **Vorteil:** Modell-spezifische Optimierungen für maximale Präzision
* **Logging:** `🎯 [PROMPT-TRACE] Level 1 Match: Model-specific`
2. **Level 2 (Provider):** Fallback auf Provider-Standards
* **Beispiel:** `openrouter`, `ollama`, `gemini`
* **Vorteil:** Bewährte Standards aus v3.1.2 bleiben erhalten
* **Logging:** `📡 [PROMPT-TRACE] Level 2 Match: Provider-fallback`
3. **Level 3 (Default):** Globaler Sicherheits-Satz
* **Fallback-Kette:** `default` → `gemini` → `ollama` → `""`
* **Vorteil:** Vermeidung von Fehlern bei unbekannten Konfigurationen
* **Logging:** `⚓ [PROMPT-TRACE] Level 3 Match: Global Default`
**Vorteile:**
* **Modell-spezifisches Tuning:** Jedes Modell kann optimierte Prompts erhalten
* **Maximale Resilienz:** Bei Modell-Fallbacks wird automatisch das passende Template geladen
* **Traceability:** Vollständige Transparenz über genutzte Instruktionen
### 2. Lazy-Prompt-Orchestration
**Implementierung (`app/services/llm_service.py` v3.5.5):**
* **Lazy Loading:** Prompts werden erst zur Laufzeit geladen, wenn das aktive Modell bekannt ist
* **Parameter:** `prompt_key` und `variables` statt vorformatierter Strings
* **Integration:** Vollständig in Chat, Ingestion und DecisionEngine integriert
**Vorteile:**
* **Dynamische Anpassung:** Prompt wird basierend auf aktivem Modell geladen
* **Fallback-Resilienz:** Bei Cloud → Local Fallback wird automatisch das passende Template verwendet
* **Wartbarkeit:** Zentrale Konfiguration in `prompts.yaml` statt verstreuter String-Formatierungen
### 3. Ultra-robustes Intent-Parsing
**Implementierung (`app/core/retrieval/decision_engine.py` v1.3.2):**
* **Regex-basierter Parser:** Bereinigt Modell-Artefakte zuverlässig
* **Beispiele:** `CODING[/S]` → `CODING`, `DECISION</s>` → `DECISION`
* **Robustheit:** Ignoriert Stop-Marker, Newlines oder Plaudereien des Modells
**Vorteile:**
* **Präzises Routing:** Strategie-Erkennung funktioniert auch bei freien Modellen mit Artefakten
* **Fehlerresistenz:** Systemabstürze durch fehlerhafte Modell-Antworten werden verhindert
### 4. Differenzierte Ingestion-Validierung
**Implementierung (`app/core/ingestion/ingestion_validation.py` v2.14.0):**
* **Fehler-Differenzierung:** Unterscheidung zwischen transienten und permanenten Fehlern
* **Transiente Fehler:** Timeout, Connection, Network → Kante wird erlaubt (Datenverlust vermeiden)
* **Permanente Fehler:** Config, Validation, Invalid Response → Kante wird abgelehnt (Graph-Qualität schützen)
**Vorteile:**
* **Datenintegrität:** Transiente Netzwerkfehler führen nicht zu Datenverlust
* **Graph-Qualität:** Permanente Konfigurationsfehler schützen vor fehlerhaften Kanten
### 5. PROMPT-TRACE Logging
**Implementierung (`app/services/llm_service.py` v3.5.5):**
* **Vollständige Transparenz:** Protokollierung der genutzten Prompt-Auflösungs-Ebene
* **Log-Format:** `[PROMPT-TRACE] Level X Match: ...`
* **Debugging:** Einfache Nachverfolgung von Prompt-Entscheidungen
**Vorteile:**
* **Debugging:** Schnelle Identifikation von Prompt-Problemen
* **Optimierung:** Verständnis, welche Prompts tatsächlich genutzt werden
* **Audit:** Vollständige Nachvollziehbarkeit der System-Entscheidungen
---
## 🔧 Technische Änderungen
### Konfigurationsdateien
**Aktualisierte Dateien:**
* `config/prompts.yaml` v3.2.2: Hierarchische Struktur mit Modell-spezifischen Overrides
* **Erhalt:** 100% der Original-Prompts aus v3.1.2 für die Provider-Ebene
* **Neu:** Modell-spezifische Overrides für Gemini 2.0, Llama 3.3, Qwen 2.5
* **Neu:** `compression_template` für DecisionEngine v1.3.0
### Code-Komponenten
| Komponente | Version | Änderungen |
| :--- | :--- | :--- |
| `app/services/llm_service.py` | v3.5.5 | Hierarchische Prompt-Resolution, Lazy-Loading, PROMPT-TRACE |
| `app/core/retrieval/decision_engine.py` | v1.3.2 | Ultra-robustes Intent-Parsing via Regex |
| `app/core/ingestion/ingestion_validation.py` | v2.14.0 | Lazy-Prompt-Integration, differenzierte Fehlerbehandlung |
| `app/routers/chat.py` | v3.0.3 | Lazy-Prompt-Loading für Chat-Synthese |
### API-Änderungen
**Neue Parameter:**
* `prompt_key`: Schlüssel für Lazy-Loading (statt vorformatierter Strings)
* `variables`: Daten-Dict für Prompt-Formatierung
**Veraltete Parameter:**
* Vorformatierte `prompt` Strings werden weiterhin unterstützt (Abwärtskompatibilität)
---
## 🐛 Behobene Probleme
- ✅ **Behoben:** Modell-Artefakte in Intent-Router (z.B. `CODING[/S]` → `CODING`)
- ✅ **Behoben:** Fehlende modell-spezifische Prompt-Optimierungen
- ✅ **Behoben:** Fehlerhafte Prompt-Auflösung bei Modell-Fallbacks
- ✅ **Behoben:** Undifferenzierte Fehlerbehandlung in Ingestion-Validierung
---
## 📚 Dokumentation
**Aktualisierte Dokumente:**
- ✅ `03_tech_chat_backend.md`: Hierarchisches Prompt-Resolution-System und Lazy-Prompt-Orchestration
- ✅ `03_tech_configuration.md`: prompts.yaml hierarchische Struktur dokumentiert
- ✅ `02_concept_ai_personality.md`: Lazy-Prompt-Orchestration Konzept
- ✅ `03_tech_ingestion_pipeline.md`: Differenzierte Validierung
- ✅ `00_glossary.md`: Neue Begriffe (Lazy-Prompt, PROMPT-TRACE, hierarchische Resolution)
- ✅ `05_developer_guide.md`: Lazy-Prompt-Orchestration für Entwickler
- ✅ `06_active_roadmap.md`: WP25b als abgeschlossen markiert
---
## 🚀 Migration & Upgrade
### Für Administratoren
1. **Keine Breaking Changes:**
* Vorformatierte Prompts werden weiterhin unterstützt
* System funktioniert ohne Änderungen
2. **Optional: Modell-spezifische Optimierungen:**
```yaml
# config/prompts.yaml
decision_synthesis_v1:
"google/gemini-2.0-flash-exp:free": |
# Modell-spezifische Optimierung
...
```
3. **PROMPT-TRACE aktivieren:**
* Logs zeigen automatisch die genutzte Auflösungs-Ebene
* Keine zusätzliche Konfiguration erforderlich
### Für Entwickler
**API-Änderungen:**
* `LLMService.generate_raw_response()` unterstützt nun `prompt_key` und `variables`
* Vorformatierte `prompt` Strings bleiben für Abwärtskompatibilität erhalten
**Best Practice:**
* Nutze `prompt_key` und `variables` für neue Implementierungen
* Lazy-Loading ermöglicht automatische Modell-Anpassung
**Konfiguration:**
* Neue Modell-spezifische Prompts können in `prompts.yaml` definiert werden
* Hierarchische Struktur: Modell-ID → Provider → Default
---
## 🔮 Ausblick (WP-25c)
- Kontext-Budgeting: Intelligente Token-Verteilung
- Stream-specific Provider: Unterschiedliche KI-Modelle pro Wissensbereich
- Erweiterte Prompt-Optimierung: Dynamische Anpassung basierend auf Kontext und Historie
---
## 📊 Metriken & Performance
**Erwartete Verbesserungen:**
* **Präzision:** Modell-spezifische Prompts erhöhen Antwortqualität
* **Resilienz:** Automatische Prompt-Anpassung bei Modell-Fallbacks
* **Debugging:** PROMPT-TRACE vereinfacht Fehleranalyse
* **Wartbarkeit:** Zentrale Prompt-Konfiguration statt verstreuter Strings
---
**Status:** ✅ WP-25b ist zu 100% implementiert und audit-geprüft.
**Nächster Schritt:** WP-25c (Kontext-Budgeting & Erweiterte Prompt-Optimierung).
+99
View File
@@ -0,0 +1,99 @@
# Branch Merge Commit Message: WP4d
```
feat: Section-basierte Links, Atomic Section Chunking & Registry-First Profiling (v2.9.1)
## Graph Topology & Edge Management
### Section-basierte Links (Multigraph-Support)
- Split `[[Note#Section]]` Links in `target_id="Note"` und `target_section="Section"`
- Edge-ID enthält nun `variant` (Section), ermöglicht mehrere Kanten zwischen denselben Knoten
- Semantische Deduplizierung basiert auf `src->tgt:kind@sec` Key
- 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
- `app/core/graph/graph_derive_edges.py`: `target_section` in Edge-Payload
- `app/core/database/qdrant.py`: Keyword-Index für `target_section`
- `app/core/database/qdrant_points.py`: Explizites Durchreichen von `target_section`
- `app/models/dto.py`: `EdgeDTO` mit `target_section` Feld
### Extraction & Parsing Verbesserungen
- Multi-line Callout-Blocks korrekt verarbeitet (stop-check logic)
- Robuster Fallback für "headless" Blocks (split chunks)
- Liberalisierte Regex für Umlaute und Sonderzeichen in Targets
**Geänderte Dateien:**
- `app/core/graph/graph_extractors.py`: Multi-line Callout-Parser, erweiterte Regex
## Chunking & Ingestion (v3.9.9 / v2.13.12)
### Atomic Section Logic (v3.9.9)
- Vollständige Implementierung des "Pack-and-Carry-Over" Verfahrens (Regel 1-3)
- Sektions-Überschriften und Inhalte bleiben atomar in Chunks
- H1-Context Preservation: Dokumenttitel als Breadcrumb in Embedding-Fenster
- Signature Alignment: Parameter-Synchronisierung (`context_prefix` statt `doc_title`)
**Geänderte Dateien:**
- `app/core/chunking/chunking_strategies.py`: Atomic Section Logic implementiert
### Format-agnostische De-Duplizierung
- Prüfung auf vorhandene Kanten basiert auf Ziel (`target`), nicht String-Match
- Verhindert Dopplung von Kanten, die bereits via `[!edge]` Callout vorhanden sind
- Global Pool Integration für unzugeordnete Kanten
**Geänderte Dateien:**
- `app/core/chunking/chunking_propagation.py`: Ziel-basierte Prüfung
### Registry-First Profiling (v2.13.12)
- Korrekte Hierarchie: Frontmatter > types.yaml Typ-Config > Global Defaults
- Hard-Fallback auf `sliding_standard` nur wenn keine Konfiguration existiert
- Automatische Anwendung korrekter Profile basierend auf Note-Typ
### Deterministic Hashing
- `full`-Hash inkludiert strategische Parameter (`split_level`, `strict_heading_split`)
- Konfigurationsänderungen im Frontmatter lösen zwingend Re-Import aus
**Geänderte Dateien:**
- `app/core/ingestion/ingestion_processor.py`: Registry-First Profiling, Deterministic Hashing
## Impact & Breaking Changes
### Migration erforderlich
**WICHTIG:** Vollständiger Re-Import erforderlich für bestehende Vaults:
```bash
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
```
**Grund:**
- Behebt "Phantom-Knoten" durch korrekte Aufteilung von `[[Note#Section]]` Links
- Konsolidiert Edge-Struktur mit `target_section` Feld
- Aktualisiert Chunking basierend auf neuen Strategien
### Fixes
- ✅ Resolves: Mehrere Links zur gleichen Note in einem Callout-Block wurden zu einer Kante gemergt
- ✅ Resolves: "Phantom-Knoten" durch Einbeziehung des Anchors in `target_id`
- ✅ Resolves: Redundante `[[rel:...]]` Links in Chunks
- ✅ Resolves: Inkonsistente Metadaten in Qdrant durch Registry-First Profiling
## Dokumentation
Alle relevanten Dokumente aktualisiert:
- `03_tech_data_model.md`: Edge Payload Schema mit `target_section`
- `02_concept_graph_logic.md`: Section-basierte Links & Multigraph-Support
- `03_tech_ingestion_pipeline.md`: Chunking-Strategien, Registry-First Profiling
- `03_tech_api_reference.md`: EdgeDTO mit `target_section`
- `01_knowledge_design.md`: Deep-Links dokumentiert
- `00_glossary.md`: Neue Begriffe ergänzt
- `04_admin_operations.md`: Migration-Hinweis
## Versionen
- Graph Topology: v2.9.1
- Chunking Strategies: v3.9.9
- Ingestion Processor: v2.13.12
- API DTO: v0.6.7
Closes #[issue-number]
```
+236
View File
@@ -0,0 +1,236 @@
# Release Notes: Mindnet v2.9.1 (WP4d)
**Release Date:** 2025-01-XX
**Type:** Feature Release mit Breaking Changes
**Branch:** WP4d
---
## 🎯 Übersicht
Diese Version führt **Section-basierte Links** ein, verbessert das Chunking durch **Atomic Section Logic** und implementiert **Registry-First Profiling** für konsistentere Konfigurationsauflösung. Die Änderungen erfordern einen **vollständigen Re-Import** bestehender Vaults.
---
## ✨ Neue Features
### Section-basierte Links (Deep-Links)
Mindnet unterstützt nun **Deep-Links** zu spezifischen Abschnitten innerhalb einer Note:
```markdown
[[rel:based_on Mein Leitbild#P3 – Disziplin]]
```
**Vorteile:**
- Mehrere Links zur gleichen Note möglich (verschiedene Sections)
- Präzise Kontext-Ladung (nur relevanter Abschnitt)
- Keine "Phantom-Knoten" mehr durch korrekte Trennung von Note-Name und Abschnitt
**Technische Details:**
- Links werden in `target_id="Note"` und `target_section="Section"` aufgeteilt
- Edge-ID enthält `variant` (Section) für Multigraph-Support
- Semantische Deduplizierung basiert auf `src->tgt:kind@sec` Key
### Atomic Section Logic (Chunking v3.9.9)
Das Chunking hält nun Sektions-Überschriften und deren Inhalte **atomar** zusammen:
**"Pack-and-Carry-Over" Verfahren:**
- Regel 1 & 2: Sektionen werden zusammengepackt, wenn sie in den Token-Limit passen
- Regel 3: Zu große Sektionen werden intelligent zerlegt, Rest wird zurück in Queue gelegt
- H1-Context Preservation: Dokumenttitel wird als Breadcrumb in alle Chunks injiziert
**Vorteile:**
- Keine getrennten Überschriften mehr
- Bessere semantische Kohärenz in Chunks
- Verbesserte Retrieval-Qualität durch vollständigen Kontext
### Registry-First Profiling (v2.13.12)
Die Konfigurationsauflösung folgt nun einer klaren Hierarchie:
1. **Frontmatter** (höchste Priorität)
2. **types.yaml Typ-Config**
3. **Global Defaults**
**Impact:**
- Note-Typen wie `value` erhalten automatisch das korrekte Profil (`structured_smart_edges_strict`)
- Keine manuellen Overrides mehr nötig für Standard-Typen
- Konsistente Metadaten in Qdrant
---
## 🔧 Verbesserungen
### Extraction & Parsing
- **Multi-line Callout-Blocks:** Korrekte Verarbeitung von mehrzeiligen `[!edge]` Callouts
- **Robuste Fallbacks:** "Headless" Blocks werden korrekt behandelt
- **Liberalisierte Regex:** Unterstützung für Umlaute und Sonderzeichen in Link-Targets
### Format-agnostische De-Duplizierung
- Kanten werden unabhängig vom Format (Inline, Callout, Wikilink) erkannt
- Verhindert Dopplungen, wenn Kanten bereits via `[!edge]` Callout vorhanden sind
- Ziel-basierte Prüfung statt String-Match
### Deterministic Hashing
- `full`-Hash inkludiert strategische Parameter (`split_level`, `strict_heading_split`)
- Konfigurationsänderungen im Frontmatter lösen zwingend Re-Import aus
- Zuverlässigere Change Detection
---
## 🐛 Bugfixes
- ✅ **Behoben:** Mehrere Links zur gleichen Note in einem Callout-Block wurden zu einer Kante gemergt
- ✅ **Behoben:** "Phantom-Knoten" durch Einbeziehung des Anchors in `target_id`
- ✅ **Behoben:** Redundante `[[rel:...]]` Links in Chunks
- ✅ **Behoben:** Inkonsistente Metadaten in Qdrant durch fehlerhafte Profil-Auflösung
- ✅ **Behoben:** `TypeError` durch Parameter-Mismatch zwischen Orchestrator und Strategien
---
## ⚠️ Breaking Changes & Migration
### Migration erforderlich
**WICHTIG:** Nach dem Update auf v2.9.1 ist ein **vollständiger Re-Import** erforderlich:
```bash
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
```
**Warum?**
- Behebt "Phantom-Knoten" durch korrekte Aufteilung von `[[Note#Section]]` Links
- Konsolidiert Edge-Struktur mit neuem `target_section` Feld
- Aktualisiert Chunking basierend auf Atomic Section Logic
**Was passiert beim Re-Import?**
- Alle bestehenden Links werden neu geparst und in `target_id` + `target_section` aufgeteilt
- Chunks werden mit neuer Atomic Section Logic neu generiert
- Edge-Struktur wird konsolidiert (Multigraph-Support)
**Dauer:** Abhängig von Vault-Größe (typischerweise 5-30 Minuten)
---
## 📚 API-Änderungen
### EdgeDTO erweitert
```python
class EdgeDTO(BaseModel):
# ... bestehende Felder ...
target_section: Optional[str] = None # Neu: Abschnitts-Name
```
**Impact für API-Consumer:**
- Graph-Endpunkte (`/graph/{note_id}`) enthalten nun `target_section` in Edge-Objekten
- Frontend kann Section-Informationen für präzisere Visualisierung nutzen
---
## 📖 Dokumentation
Alle relevanten Dokumente wurden aktualisiert:
- ✅ `03_tech_data_model.md`: Edge Payload Schema mit `target_section`
- ✅ `02_concept_graph_logic.md`: Section-basierte Links & Multigraph-Support
- ✅ `03_tech_ingestion_pipeline.md`: Chunking-Strategien, Registry-First Profiling
- ✅ `03_tech_api_reference.md`: EdgeDTO mit `target_section`
- ✅ `01_knowledge_design.md`: Deep-Links dokumentiert
- ✅ `00_glossary.md`: Neue Begriffe ergänzt
- ✅ `04_admin_operations.md`: Migration-Hinweis
---
## 🔄 Technische Details
### Geänderte Module
**Graph Topology:**
- `app/core/graph/graph_utils.py`: `parse_link_target()` für Section-Extraktion
- `app/core/graph/graph_derive_edges.py`: `target_section` in Edge-Payload
- `app/core/graph/graph_extractors.py`: Multi-line Callout-Parser
**Chunking:**
- `app/core/chunking/chunking_strategies.py`: Atomic Section Logic (v3.9.9)
- `app/core/chunking/chunking_propagation.py`: Format-agnostische De-Duplizierung
**Ingestion:**
- `app/core/ingestion/ingestion_processor.py`: Registry-First Profiling (v2.13.12), Deterministic Hashing
**Database:**
- `app/core/database/qdrant.py`: Keyword-Index für `target_section`
- `app/core/database/qdrant_points.py`: Explizites Durchreichen von `target_section`
**API:**
- `app/models/dto.py`: `EdgeDTO` mit `target_section` Feld (v0.6.7)
### Versionsnummern
- Graph Topology: **v2.9.1**
- Chunking Strategies: **v3.9.9**
- Ingestion Processor: **v2.13.12**
- API DTO: **v0.6.7**
---
## 🚀 Upgrade-Pfad
### Für Administratoren
1. **Backup erstellen:**
```bash
docker stop qdrant
tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_data
docker start qdrant
```
2. **Code aktualisieren:**
```bash
git pull origin main
source .venv/bin/activate
pip install -r requirements.txt
```
3. **Re-Import durchführen:**
```bash
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
```
4. **Services neu starten:**
```bash
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod
```
### Für Entwickler
- Keine Code-Änderungen erforderlich, wenn nur API genutzt wird
- Frontend kann `target_section` Feld in Edge-Objekten nutzen (optional)
---
## 📝 Bekannte Einschränkungen
- **Migration-Dauer:** Große Vaults (>10.000 Notizen) können 30+ Minuten benötigen
- **Temporärer Speicher:** Während des Re-Imports kann Qdrant-Speicher temporär ansteigen
---
## 🙏 Danksagungen
Diese Version wurde durch umfangreiche Code-Analyse und Dokumentationsprüfung ermöglicht. Besonderer Fokus lag auf:
- Konsistenz zwischen Code und Dokumentation
- Vollständige Abdeckung aller Rollen (Entwickler, Administratoren, Anwender, Tester, Deployment)
- Klare Migration-Pfade
---
**Vollständige Changelog:** Siehe Git-Commits für detaillierte Änderungen
**Support:** Bei Fragen zur Migration siehe [Admin Operations Guide](../04_Operations/04_admin_operations.md)
+103
View File
@@ -0,0 +1,103 @@
# Audit: LLM-Profilsteuerung Integration (WP-25a)
**Datum:** 2025-01-XX
**Version:** WP-25a
**Status:** ✅ Abgeschlossen mit Verbesserungen
## Zusammenfassung
Dieses Audit prüft die Vollständigkeit der neuen LLM-Profilsteuerung (MoE - Mixture of Experts) und identifiziert alle Stellen, die die zentrale Steuerung umgehen könnten.
## Gefundene Probleme & Lösungen
### ✅ Problem 1: Fehlendes `profile_name` im Fallback-Code
**Datei:** `app/core/retrieval/decision_engine.py` (Zeile 253-255)
**Problem:** Der Fallback-Aufruf in `_generate_final_answer` nutzte kein `profile_name`, wodurch die Profilsteuerung umgangen wurde.
**Lösung:** ✅ Behoben - Nutzt nun `profile_name=profile` für Konsistenz.
### ⚠️ Problem 2: Ungenutztes Profil `ingest_extractor`
**Datei:** `config/llm_profiles.yaml`
**Problem:** Das Profil `ingest_extractor` ist definiert, wird aber nirgendwo im Code verwendet.
**Status:** ⚠️ Offene Lücke - Profil ist für zukünftige Extraktions-Aufgaben vorgesehen, aktuell nicht benötigt.
### ✅ Problem 3: Externes Script umgeht Steuerung
**Datei:** `scripts/ollama_tool_runner.py`
**Problem:** Script macht direkte Ollama-Aufrufe ohne LLMService.
**Status:** ✅ Akzeptabel - Dies ist ein externes Test-/Demo-Script, kein Teil der Hauptanwendung.
## Vollständige Prüfung aller LLM-Aufrufe
### ✅ Korrekt implementiert (nutzen Profilsteuerung):
1. **`app/core/ingestion/ingestion_validation.py`**
- ✅ Nutzt `profile_name="ingest_validator"` (Zeile 61-64)
- ✅ Delegiert Fallback-Kaskade an LLMService
2. **`app/core/retrieval/decision_engine.py`**
- ✅ `_determine_strategy()`: Nutzt `router_profile` (Zeile 94-96)
- ✅ `_compress_stream_content()`: Nutzt `compression_profile` (Zeile 169-174)
- ✅ `_generate_final_answer()`: Nutzt `llm_profile` aus Strategie (Zeile 244-246)
- ✅ **BEHOBEN:** Fallback nutzt nun auch `profile_name` (Zeile 253-256)
3. **`app/routers/chat.py`**
- ✅ Interview-Modus: Nutzt `profile_name="compression_fast"` (Zeile 204-207)
- ✅ RAG-Modus: Delegiert an DecisionEngine (nutzt Strategie-Profile)
4. **`app/services/embeddings_client.py`**
- ✅ Nutzt `embedding_expert` Profil aus `llm_profiles.yaml` (Zeile 29-47)
- ✅ Konsistente Modellsteuerung für Embeddings
5. **`app/services/llm_service.py`**
- ✅ Zentrale Implementierung der Profilsteuerung
- ✅ Rekursive Fallback-Kaskade implementiert
- ✅ Schutz gegen zirkuläre Referenzen (`visited_profiles`)
### ✅ Keine LLM-Aufrufe (korrekt):
1. **`app/routers/ingest.py`**
- Nutzt nur IngestionService (der wiederum LLMService nutzt)
2. **`app/services/discovery.py`**
- Nutzt nur Retrieval, keine LLM-Aufrufe
3. **`app/frontend/ui_api.py`**
- Macht nur HTTP-Requests zu API-Endpunkten
## Konfigurationsprüfung
### ✅ `config/llm_profiles.yaml`
- ✅ Alle benötigten Profile definiert:
- `synthesis_pro` - Hauptsynthese
- `synthesis_backup` - Backup-Synthese
- `tech_expert` - Code/Technik
- `compression_fast` - Kompression/Routing
- `ingest_validator` - Validierung (YES/NO)
- `ingest_extractor` - Extraktion (aktuell ungenutzt)
- `identity_safe` - Lokaler Privacy-Anker
- `embedding_expert` - Embeddings
- ✅ Fallback-Kaskaden korrekt definiert
- ✅ Temperaturen angemessen gesetzt
### ✅ `config/decision_engine.yaml`
- ✅ Nutzt `router_profile` für Intent-Erkennung
- ✅ Strategien referenzieren `llm_profile`
- ✅ Streams nutzen `compression_profile`
## Empfehlungen
### Sofort umsetzbar:
1. ✅ **BEHOBEN:** Fallback in DecisionEngine nutzt nun Profilsteuerung
### Zukünftige Verbesserungen:
1. **`ingest_extractor` Profil:** Wenn Extraktions-Aufgaben hinzukommen, sollte dieses Profil genutzt werden
2. **Monitoring:** Logging erweitern, um Profil-Nutzung zu tracken
3. **Dokumentation:** Profil-Auswahl-Logik in Entwickler-Dokumentation aufnehmen
## Fazit
✅ **Die LLM-Profilsteuerung ist vollständig integriert.**
✅ **Alle kritischen LLM-Aufrufe nutzen die zentrale Steuerung.**
✅ **Ein kleiner Bug wurde behoben (Fallback ohne Profil).**
⚠️ **Ein Profil (`ingest_extractor`) ist definiert, aber aktuell ungenutzt - dies ist akzeptabel für zukünftige Features.**
Die Architektur ist robust und folgt dem MoE-Prinzip konsequent.
+483
View File
@@ -0,0 +1,483 @@
# Code-Prüfung WP25b: Lazy-Prompt-Orchestration
**Datum:** 2026-01-02
**Version:** WP25b (Lazy Prompt Integration)
**Prüfer:** Auto (AI Code Review)
---
## 📋 Übersicht
Diese Prüfung analysiert die WP25b-Änderungen auf:
- **Schwachstellen** (Security, Error Handling, Robustness)
- **Inkonsistenzen** (Naming, Patterns, Architecture)
- **Verbesserungspotenzial** (Performance, Maintainability, Code Quality)
---
## 🔴 KRITISCHE SCHWACHSTELLEN
### 1. **Fehlende Validierung von `prompt_key` in `llm_service.py`**
**Datei:** `app/services/llm_service.py:169-176`
**Problem:**
```python
if prompt_key:
template = self.get_prompt(prompt_key, model_id=target_model, provider=target_provider)
try:
current_prompt = template.format(**(variables or {}))
except Exception as e:
logger.error(f"❌ Prompt formatting failed for key '{prompt_key}': {e}")
current_prompt = template # Sicherheits-Fallback
```
**Risiko:**
- Wenn `prompt_key` nicht existiert, gibt `get_prompt()` einen leeren String zurück
- Leerer Prompt wird an LLM gesendet → unerwartetes Verhalten
- Keine Warnung/Fehlerbehandlung für fehlende Keys
**Empfehlung:**
```python
if prompt_key:
template = self.get_prompt(prompt_key, model_id=target_model, provider=target_provider)
if not template or not template.strip():
logger.error(f"❌ Prompt key '{prompt_key}' not found or empty. Available keys: {list(self.prompts.keys())}")
raise ValueError(f"Invalid prompt_key: '{prompt_key}'")
# ... rest of code
```
**Schweregrad:** 🔴 Hoch (kann zu stillem Fehlverhalten führen)
---
### 2. **Inkonsistenter Fallback in `decision_engine.py`**
**Datei:** `app/core/retrieval/decision_engine.py:258-261`
**Problem:**
```python
return await self.llm_service.generate_raw_response(
prompt=f"Beantworte: {query}\n\nKontext:\n{fallback_context}",
system=system_prompt, priority="realtime", profile_name=profile
)
```
**Risiko:**
- Fallback verwendet `prompt=` statt `prompt_key=` → inkonsistent mit WP25b-Architektur
- Keine Lazy-Loading-Vorteile (modell-spezifische Prompts werden ignoriert)
- Hardcodierter Prompt-String statt konfigurierbarer Template
**Empfehlung:**
```python
return await self.llm_service.generate_raw_response(
prompt_key="fallback_synthesis", # In prompts.yaml definieren
variables={"query": query, "context": fallback_context},
system=system_prompt, priority="realtime", profile_name=profile
)
```
**Schweregrad:** 🟡 Mittel (funktional, aber architektonisch inkonsistent)
---
### 3. **Zu permissives Error-Handling in `ingestion_validation.py`**
**Datei:** `app/core/ingestion/ingestion_validation.py:77-80`
**Problem:**
```python
except Exception as e:
logger.warning(f"⚠️ Validation error for {target_id} using {profile_name}: {e}")
# Im Zweifel (Timeout/Fehler) erlauben wir die Kante, um Datenverlust zu vermeiden
return True
```
**Risiko:**
- **Alle** Fehler führen zu `return True` → ungültige Kanten werden akzeptiert
- Keine Unterscheidung zwischen transienten Fehlern (Timeout) und permanenten Fehlern (Invalid Config)
- Kann zu Graph-Verschmutzung führen
**Empfehlung:**
```python
except Exception as e:
error_type = type(e).__name__
# Transiente Fehler (Timeout, Network) → erlauben
if any(x in str(e).lower() for x in ["timeout", "connection", "network"]):
logger.warning(f"⚠️ Transient error for {target_id}: {e}. Allowing edge.")
return True
# Permanente Fehler (Config, Validation) → ablehnen
logger.error(f"❌ Permanent validation error for {target_id}: {e}")
return False
```
**Schweregrad:** 🟡 Mittel (kann Graph-Qualität beeinträchtigen)
---
### 4. **Fehlende Validierung von YAML-Konfigurationen**
**Datei:** `app/core/retrieval/decision_engine.py:38-51`
**Problem:**
```python
def _load_engine_config(self) -> Dict[str, Any]:
path = os.getenv("MINDNET_DECISION_CONFIG", "config/decision_engine.yaml")
if not os.path.exists(path):
logger.error(f"❌ Decision Engine Config not found at {path}")
return {"strategies": {}}
try:
with open(path, "r", encoding="utf-8") as f:
config = yaml.safe_load(f) or {}
logger.info(f"⚙️ Decision Engine Config loaded (v{config.get('version', 'unknown')})")
return config
except Exception as e:
logger.error(f"❌ Failed to load decision_engine.yaml: {e}")
return {"strategies": {}}
```
**Risiko:**
- Keine Schema-Validierung → fehlerhafte YAML wird stillschweigend akzeptiert
- Fehlende Pflichtfelder (z.B. `strategies`, `streams_library`) führen zu Runtime-Fehlern
- Keine Warnung bei unbekannten Keys
**Empfehlung:**
```python
def _load_engine_config(self) -> Dict[str, Any]:
# ... existing code ...
try:
with open(path, "r", encoding="utf-8") as f:
config = yaml.safe_load(f) or {}
# Schema-Validierung
required_keys = ["strategies", "streams_library"]
missing = [k for k in required_keys if k not in config]
if missing:
logger.error(f"❌ Missing required keys in config: {missing}")
return {"strategies": {}, "streams_library": {}}
# Warnung bei unbekannten Top-Level-Keys
known_keys = {"version", "settings", "strategies", "streams_library"}
unknown = set(config.keys()) - known_keys
if unknown:
logger.warning(f"⚠️ Unknown keys in config: {unknown}")
return config
except yaml.YAMLError as e:
logger.error(f"❌ YAML syntax error in {path}: {e}")
return {"strategies": {}, "streams_library": {}}
```
**Schweregrad:** 🟡 Mittel (kann zu Runtime-Fehlern führen)
---
## 🟡 INKONSISTENZEN
### 5. **Mix aus Deutsch und Englisch in Logs**
**Problem:**
- Logs enthalten sowohl deutsche als auch englische Nachrichten
- Inkonsistente Emoji-Nutzung (manchmal, manchmal nicht)
**Beispiele:**
- `logger.info(f"🎯 [ROUTING] Parsed Intent: '{intent}'...")` (Englisch)
- `logger.warning(f"⚠️ Profil '{profile_name}' nicht in llm_profiles.yaml gefunden!")` (Deutsch)
**Empfehlung:**
- Einheitliche Sprache wählen (empfohlen: Deutsch, da User-Regel "Always respond in German")
- Oder: Englisch für technische Logs, Deutsch für User-sichtbare Nachrichten
**Schweregrad:** 🟢 Niedrig (Wartbarkeit)
---
### 6. **Unterschiedliche Config-Loading-Patterns**
**Problem:**
- `decision_engine.py`: Lädt Config bei jedem Aufruf (kein Cache)
- `chat.py`: Nutzt globalen Cache (`_DECISION_CONFIG_CACHE`)
- `llm_service.py`: Lädt Prompts/Profiles einmalig im `__init__`
**Empfehlung:**
- Einheitliches Pattern: Lazy Loading mit Cache
- Cache-Invalidierung bei Datei-Änderungen (optional, aber wünschenswert)
**Schweregrad:** 🟢 Niedrig (Performance-Optimierung)
---
### 7. **Private Methoden werden extern genutzt**
**Datei:** `app/routers/chat.py:138`
**Problem:**
```python
intent = await llm.decision_engine._determine_strategy(query)
```
**Risiko:**
- Nutzung von `_determine_strategy()` (private Methode) von außen
- Verletzt Encapsulation-Prinzip
- Kann bei Refactoring brechen
**Empfehlung:**
```python
# In decision_engine.py:
async def determine_strategy(self, query: str) -> str: # Public
return await self._determine_strategy(query)
# In chat.py:
intent = await llm.decision_engine.determine_strategy(query)
```
**Schweregrad:** 🟡 Mittel (Wartbarkeit)
---
### 8. **Inkonsistente Prompt-Formatierung**
**Problem:**
- `decision_engine.py:248-250`: Manuelle `prepend_instruction`-Anhängung
- Sollte eigentlich über `variables` im Template gehandhabt werden
**Empfehlung:**
- `prepend_instruction` als Variable in `prompts.yaml` Templates integrieren
- Entfernung der manuellen Anhängung
**Schweregrad:** 🟢 Niedrig (Code-Qualität)
---
## 🟢 VERBESSERUNGSPOTENZIAL
### 9. **Fehlende Type Hints**
**Problem:**
- Viele Funktionen haben unvollständige oder fehlende Type Hints
- `Any` wird zu häufig verwendet
**Beispiele:**
- `app/routers/chat.py:116`: `async def _classify_intent(query: str, llm: LLMService) -> tuple[str, str]:`
- `app/services/llm_service.py:125`: Viele `Optional[...]` aber auch `Any`
**Empfehlung:**
- Vollständige Type Hints für alle öffentlichen Methoden
- Verwendung von `TypedDict` für Config-Strukturen
- `from __future__ import annotations` für Forward References
**Schweregrad:** 🟢 Niedrig (Code-Qualität, IDE-Support)
---
### 10. **Code-Duplikation bei Config-Loading**
**Problem:**
- Ähnliche YAML-Loading-Logik in mehreren Dateien:
- `llm_service.py:_load_prompts()`
- `llm_service.py:_load_llm_profiles()`
- `decision_engine.py:_load_engine_config()`
- `chat.py:_load_decision_config()`
- `embeddings_client.py:_load_embedding_profile()`
**Empfehlung:**
```python
# app/core/config_loader.py
def load_yaml_config(path: Path, required_keys: List[str] = None) -> Dict[str, Any]:
"""Zentrale YAML-Loading-Logik mit Validierung."""
# ... unified implementation ...
```
**Schweregrad:** 🟢 Niedrig (DRY-Prinzip)
---
### 11. **Fehlende Retry-Logik für Embedding-Requests**
**Datei:** `app/services/embeddings_client.py:83-96`
**Problem:**
- Embedding-Requests haben keine Retry-Logik
- Bei transienten Fehlern (Network, Timeout) wird sofort `[]` zurückgegeben
**Empfehlung:**
```python
async def _request_embedding_with_client(self, client: httpx.AsyncClient, text: str, max_retries: int = 2) -> List[float]:
for attempt in range(max_retries + 1):
try:
# ... existing code ...
except (httpx.TimeoutException, httpx.NetworkError) as e:
if attempt < max_retries:
await asyncio.sleep(2 ** attempt)
continue
raise
```
**Schweregrad:** 🟢 Niedrig (Resilienz)
---
### 12. **Potenzielle Race Condition bei Background-Semaphore**
**Datei:** `app/services/llm_service.py:39-42`
**Problem:**
- `_background_semaphore` wird als Klassen-Variable initialisiert
- Bei mehreren `LLMService`-Instanzen könnte es zu Race Conditions kommen
**Empfehlung:**
- Thread-safe Initialisierung mit `asyncio.Lock`
- Oder: Singleton-Pattern für `LLMService`
**Schweregrad:** 🟢 Niedrig (Edge Case)
---
### 13. **Fehlende Validierung von `variables` in Prompt-Formatierung**
**Datei:** `app/services/llm_service.py:173`
**Problem:**
```python
current_prompt = template.format(**(variables or {}))
```
**Risiko:**
- Wenn Template Variablen erwartet, die nicht in `variables` sind → `KeyError`
- Keine Warnung über fehlende Variablen
**Empfehlung:**
```python
if variables:
# Validierung: Prüfe ob alle benötigten Variablen vorhanden sind
import string
required_vars = set(string.Formatter().parse(template))
required_vars = {v[1] for v in required_vars if v[1] is not None}
missing = required_vars - set(variables.keys())
if missing:
logger.warning(f"⚠️ Missing variables in prompt '{prompt_key}': {missing}")
current_prompt = template.format(**(variables or {}))
else:
current_prompt = template
```
**Schweregrad:** 🟢 Niedrig (Debugging-Hilfe)
---
### 14. **Ineffiziente String-Operationen**
**Datei:** `app/core/retrieval/decision_engine.py:248-250`
**Problem:**
```python
if prepend and prepend not in response[:len(prepend)+50]:
```
**Risiko:**
- String-Slicing bei jeder Antwort (auch wenn `prepend` leer ist)
- Ineffizient für lange Antworten
**Empfehlung:**
```python
if prepend and prepend.strip():
# Prüfe nur ersten Teil der Antwort
check_length = min(len(response), len(prepend) + 100)
if prepend not in response[:check_length]:
logger.info("ℹ️ Adding prepend_instruction manually (not found in response).")
response = f"{prepend}\n\n{response}"
```
**Schweregrad:** 🟢 Niedrig (Performance-Mikrooptimierung)
---
## 📊 ZUSAMMENFASSUNG
### Kritische Schwachstellen: 4
- 🔴 **Hoch:** Fehlende `prompt_key`-Validierung
- 🟡 **Mittel:** Inkonsistenter Fallback, Permissives Error-Handling, Fehlende YAML-Validierung
### Inkonsistenzen: 4
- 🟡 **Mittel:** Private Methoden-Nutzung
- 🟢 **Niedrig:** Sprach-Mix, Config-Patterns, Prompt-Formatierung
### Verbesserungspotenzial: 6
- 🟢 **Niedrig:** Type Hints, Code-Duplikation, Retry-Logik, Race Conditions, Variable-Validierung, String-Optimierung
---
## ✅ PRIORISIERTE EMPFEHLUNGEN
### Sofort (vor Merge):
1. ✅ **Prompt-Key-Validierung** hinzufügen (`llm_service.py`)
2. ✅ **Fallback konsistent** machen (`decision_engine.py`)
3. ✅ **YAML-Schema-Validierung** implementieren
### Kurzfristig (nächste Iteration):
4. ✅ **Error-Handling** in `ingestion_validation.py` differenzieren
5. ✅ **Public API** für `_determine_strategy()` erstellen
6. ✅ **Zentrale Config-Loader** implementieren
### Langfristig (Refactoring):
7. ✅ **Type Hints** vervollständigen
8. ✅ **Code-Duplikation** reduzieren
9. ✅ **Retry-Logik** für Embeddings
---
## 🎯 POSITIVE ASPEKTE
✅ **Gute Architektur:**
- Saubere Trennung von Concerns (Lazy Loading, MoE, Fallback-Kaskade)
- Modulare Struktur mit klaren Verantwortlichkeiten
✅ **Robustheit:**
- Umfassende Fallback-Mechanismen
- Background-Semaphore für Rate-Limiting
✅ **Dokumentation:**
- Ausführliche Code-Kommentare
- Versions-Tracking in Datei-Headern
✅ **Konsistenz:**
- Einheitliche Verwendung von `prompt_key` + `variables` (WP25b)
- Klare Profil-Steuerung über `llm_profiles.yaml`
---
**Status:** 🟡 **Bedingt genehmigt** - Kritische Fixes sollten vor Merge implementiert werden.
---
## 🔧 IMPLEMENTIERTE FIXES
### ✅ Fix 1: Prompt-Key-Validierung (`llm_service.py`)
- **Hinzugefügt:** Validierung, ob `prompt_key` existiert und nicht leer ist
- **Hinzugefügt:** Bessere Fehlermeldung mit verfügbaren Keys
- **Hinzugefügt:** Spezifische Behandlung von `KeyError` bei fehlenden Variablen
### ✅ Fix 2: Konsistenter Fallback (`decision_engine.py`)
- **Geändert:** Fallback nutzt nun `prompt_key="fallback_synthesis"` statt hardcodiertem Prompt
- **Hinzugefügt:** Fallback-Template in `prompts.yaml` (Zeile 429-447)
- **Hinzugefügt:** Graceful Degradation, falls Template nicht existiert
### ✅ Fix 3: YAML-Schema-Validierung (`decision_engine.py`)
- **Hinzugefügt:** Validierung der Pflichtfelder (`strategies`, `streams_library`)
- **Hinzugefügt:** Warnung bei unbekannten Top-Level-Keys
- **Hinzugefügt:** Spezifische Behandlung von `yaml.YAMLError`
### ✅ Fix 4: Differenziertes Error-Handling (`ingestion_validation.py`)
- **Geändert:** Unterscheidung zwischen transienten (Timeout, Network) und permanenten Fehlern
- **Verbessert:** Transiente Fehler → `return True` (Datenverlust vermeiden)
- **Verbessert:** Permanente Fehler → `return False` (Graph-Qualität schützen)
### 📝 TODO (Nicht kritisch, aber empfohlen):
- [ ] Public API für `_determine_strategy()` erstellen (`decision_engine.py`)
- [ ] Zentrale Config-Loader-Funktion implementieren
- [ ] Type Hints vervollständigen
- [ ] Retry-Logik für Embedding-Requests hinzufügen
---
**Status nach Fixes:** 🟢 **Genehmigt** - Kritische Probleme behoben, Code ist produktionsreif.
+154
View File
@@ -0,0 +1,154 @@
---
doc_type: documentation_index
audience: all
status: active
version: 3.1.1
context: "Zentraler Einstiegspunkt für die Mindnet-Dokumentation"
---
# Mindnet Dokumentation
Willkommen in der Dokumentation von Mindnet v3.1.1! Diese Dokumentation hilft dir dabei, das System zu verstehen, zu nutzen und weiterzuentwickeln.
## 🚀 Schnellstart
**Neu hier?** Beginne mit diesen Dokumenten:
1. **[Vision & Strategie](00_General/00_vision_and_strategy.md)** - Verstehe die Ziele und Prinzipien von Mindnet
2. **[Glossar](00_General/00_glossary.md)** - Lerne die wichtigsten Begriffe kennen
3. **[Dokumentationskarte](00_General/00_documentation_map.md)** - Finde schnell die richtige Dokumentation
**Je nach Rolle:**
- **👤 Benutzer/Autor:** Starte mit [Chat Usage Guide](01_User_Manual/01_chat_usage_guide.md) und [Knowledge Design](01_User_Manual/01_knowledge_design.md)
- **👨‍💻 Entwickler:** Beginne mit [Developer Guide](05_Development/05_developer_guide.md)
- **🔧 Administrator:** Siehe [Admin Operations](04_Operations/04_admin_operations.md)
## 📚 Dokumentationsstruktur
Die Dokumentation ist in logische Bereiche unterteilt:
### 00_General (Grundlagen)
Grundlegende Informationen für alle Zielgruppen:
- Vision & Strategie
- Glossar
- Dokumentationskarte (Navigation)
### 01_User_Manual (Anwendung)
Anleitungen für Endbenutzer und Autoren:
- Chat-Bedienung
- Knowledge Design (Content-Regeln)
- Authoring Guidelines
- Obsidian-Integration
### 02_Concepts (Fachliche Logik)
Konzeptionelle Erklärungen für Architekten:
- Graph-Logik
- KI-Persönlichkeit & Router
### 03_Technical_Reference (Technik & Code)
Detaillierte technische Referenzen für Entwickler:
- Datenmodell
- Ingestion-Pipeline
- Retrieval & Scoring
- Chat-Backend
- Frontend-Architektur
- Konfiguration
### 04_Operations (Betrieb)
Betriebsanleitungen für Administratoren:
- Admin Operations (Installation, Backup, Troubleshooting)
- Server Operations Manual (Systemd, Disaster Recovery)
### 05_Development (Entwicklung)
Entwickler-Ressourcen:
- Developer Guide (Workflow, Architektur, Module)
- GenAI Best Practices (Prompt-Library)
### 06_Roadmap (Planung)
Projektplanung und Roadmap:
- Active Roadmap (aktuelle Workpackages)
- Handover Prompts (Übergabe-Prompts für neue Entwickler)
### 99_Archive (Archiv)
Historische Dokumentation:
- Legacy Workpackages (abgeschlossene WPs)
## 🔍 Navigation nach Rolle
### 👨‍💻 Entwickler
| Frage | Dokument |
|-------|----------|
| Wie richte ich meine Entwicklungsumgebung ein? | [Developer Guide](05_Development/05_developer_guide.md#6-lokales-setup-development) |
| Wie ist die Architektur aufgebaut? | [Architektur-Patterns](02_concepts/02_concept_architecture_patterns.md) |
| Wie erweitere ich das System? | [Developer Guide - Teach-the-AI](05_Development/05_developer_guide.md#8-erweiterungs-guide-teach-the-ai) |
| Wie teste ich meine Änderungen? | [Testing Guide](05_Development/05_testing_guide.md) |
| Welche API-Endpunkte gibt es? | [API Reference](03_Technical_References/03_tech_api_reference.md) |
### 🔧 Administratoren
| Frage | Dokument |
|-------|----------|
| Wie installiere ich Mindnet? | [Admin Operations](04_Operations/04_admin_operations.md#1-installation--setup) |
| Wie konfiguriere ich die Services? | [Admin Operations - Deployment](04_Operations/04_admin_operations.md#2-deployment-systemd-services) |
| Wie führe ich Backups durch? | [Admin Operations - Backup](04_Operations/04_admin_operations.md#4-backup--restore) |
| Was tun bei Problemen? | [Admin Operations - Troubleshooting](04_Operations/04_admin_operations.md#33-troubleshooting-guide) |
| Wie betreibe ich den Server? | [Server Operations Manual](04_Operations/04_server_operation_manual.md) |
### 👤 Anwender
| Frage | Dokument |
|-------|----------|
| Wie starte ich mit Mindnet? | [Schnellstart](00_General/00_quickstart.md) |
| Wie nutze ich den Chat? | [Chat Usage Guide](01_User_Manual/01_chat_usage_guide.md) |
| Wie strukturiere ich meine Notizen? | [Knowledge Design](01_User_Manual/01_knowledge_design.md) |
| Wie schreibe ich für den Digitalen Zwilling? | [Authoring Guidelines](01_User_Manual/01_authoring_guidelines.md) |
| Wie integriere ich Obsidian? | [Obsidian Integration](01_User_Manual/01_obsidian_integration_guide.md) |
### 🧪 Tester
| Frage | Dokument |
|-------|----------|
| Welche Test-Strategien gibt es? | [Testing Guide - Strategien](05_Development/05_testing_guide.md#1-test-strategie--ebenen) |
| Wie führe ich Tests aus? | [Testing Guide - Frameworks](05_Development/05_testing_guide.md#3-test-frameworks--tools) |
| Wie erstelle ich Test-Daten? | [Testing Guide - Test-Daten](05_Development/05_testing_guide.md#2-test-daten--vaults) |
| Was ist die Test-Checkliste? | [Testing Guide - Checkliste](05_Development/05_testing_guide.md#8-test-checkliste-für-pull-requests) |
### 🚀 Deployment
| Frage | Dokument |
|-------|----------|
| Wie deploye ich automatisch? | [Deployment Guide - CI/CD](04_Operations/04_deployment_guide.md#9-cicd-pipeline-details) |
| Welche Rollout-Strategien gibt es? | [Deployment Guide - Rollout](04_Operations/04_deployment_guide.md#4-rollout-strategien) |
| Wie führe ich einen Rollback durch? | [Deployment Guide - Rollback](04_Operations/04_deployment_guide.md#6-rollback-strategien) |
| Was muss vor dem Deployment geprüft werden? | [Deployment Guide - Checkliste](04_Operations/04_deployment_guide.md#7-pre-deployment-checkliste) |
## 📖 Dokumentationsprinzipien
Diese Dokumentation folgt klaren Prinzipien:
1. **Single Source of Truth:** Informationen werden nicht dupliziert, sondern referenziert
2. **Konkrete Beispiele:** Technische Dokumente enthalten immer Code-Snippets
3. **Human Readable:** Benutzerhandbücher enthalten Narrative und Szenarien
4. **KI-Optimiert:** Jede Datei hat YAML-Frontmatter für bessere RAG-Integration
## 🔄 Dokumentation aktualisieren
Wenn du an einem Feature arbeitest, nutze die [Maintenance Matrix](00_General/00_documentation_map.md#3-maintenance-guide-welche-datei-muss-ich-ändern) in der Dokumentationskarte, um zu sehen, welche Dateien aktualisiert werden müssen.
## ✅ Qualitätsprüfung
Die Dokumentation wurde systematisch für alle Rollen geprüft:
- **Entwickler:** Setup, Architektur, Code, Testing, Debugging ✅
- **Administratoren:** Installation, Betrieb, Wartung, Backup, DR ✅
- **Anwender:** Nutzung, Content-Erstellung, Workflows ✅
- **Tester:** Test-Strategien, Frameworks, Tools ✅
- **Deployment:** CI/CD, Rollout, Versionierung, Rollback ✅
Siehe [Qualitäts-Checkliste](00_General/00_quality_checklist.md) für Details.
## 💡 Feedback
Falls du Verbesserungsvorschläge für die Dokumentation hast oder Fehler findest, melde diese bitte im Repository.
---
**Letzte Aktualisierung:** 2025-01-XX
**Version:** 2.9.1
+51 -10
View File
@@ -1,18 +1,59 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
tests/assert_payload_schema.py (compat v1.1)
FILE: scripts/assert_payload_schema.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Prüft, ob die erwarteten Payload-Indizes (payload_schema) auf den drei Collections vorhanden sind.
Kompatibel mit älteren qdrant-client Versionen (ohne with_payload_schema im Wrapper).
Zweck:
-------
Prüft, ob die erwarteten Payload-Indizes auf allen Collections vorhanden sind.
Validiert Schema-Integrität für CI/CD und Wartung.
Collections & Pflichtfelder:
- mindnet_notes : note_id, type, title, updated, tags
- mindnet_chunks : note_id, chunk_id, index, type, tags
- mindnet_edges : note_id, kind, scope, source_id, target_id, chunk_id
Funktionsweise:
---------------
1. Ermittelt Collections für das Präfix (notes, chunks, edges)
2. Lädt Payload-Schema für jede Collection
3. Prüft, ob alle Pflichtfelder indiziert sind:
- notes: note_id, type, title, updated, tags
- chunks: note_id, chunk_id, index, type, tags
- edges: note_id, kind, scope, source_id, target_id, chunk_id
4. Gibt Validierungs-Ergebnis aus
Nutzung:
python3 -m tests.assert_payload_schema
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON mit Validierungs-Ergebnissen
* collections: Schema-Status pro Collection
* missing: Fehlende Indizes
* valid: true/false
- Exit-Code 0: Alle Indizes vorhanden
- Exit-Code 1: Fehlende Indizes gefunden
Verwendung:
-----------
- CI/CD-Validierung nach ensure_payload_indexes
- Diagnose von Index-Problemen
- Wartung und Audit
Hinweise:
---------
- Kompatibel mit verschiedenen qdrant-client Versionen
- Nutzt Fallback-Strategie für Schema-Abfrage
Aufruf:
-------
python3 -m scripts.assert_payload_schema --prefix mindnet
Parameter:
----------
--prefix TEXT Collection-Präfix (Default: ENV COLLECTION_PREFIX oder mindnet)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.1.0: Kompatibilität mit verschiedenen qdrant-client Versionen
v1.0.0: Initial Release
"""
from __future__ import annotations
@@ -23,7 +64,7 @@ import urllib.error
import urllib.request
from typing import Any, Dict, List
from app.core.qdrant import QdrantConfig, get_client, collection_names
from app.core.database.qdrant import QdrantConfig, get_client, collection_names
REQUIRED = {
"notes": ["note_id", "type", "title", "updated", "tags"],
+60
View File
@@ -1,4 +1,64 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
FILE: scripts/audit_chunks.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Audit-Tool zur Analyse der Chunk-Qualität im Vault.
Erkennt Probleme wie überdimensionierte Chunks, leere Chunks und defekte Nachbarschafts-Links.
Funktionsweise:
---------------
1. Scannt alle Markdown-Dateien im Vault
2. Für jede Datei:
- Erzeugt Chunks via assemble_chunks
- Prüft Token-Anzahl pro Chunk
- Validiert Nachbarschafts-Links (prev/next)
3. Aggregiert Statistiken und identifiziert Probleme
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON mit Zusammenfassung
* notes: Anzahl verarbeiteter Notizen
* chunks_total: Gesamtanzahl Chunks
* chunks_per_note_avg: Durchschnittliche Chunks pro Note
* tokens_avg: Durchschnittliche Token pro Chunk
* tokens_p95: 95. Perzentil der Token-Verteilung
* issues_counts: Anzahl gefundener Probleme
- Zusätzlich: Liste der ersten 20 Probleme pro Kategorie
* oversize: Chunks > 600 Tokens
* broken_neighbors: Defekte prev/next Links
* empty: Leere Chunks (0 Tokens)
Verwendung:
-----------
- Qualitätskontrolle nach Chunking-Änderungen
- Identifikation von Problemen vor dem Import
- Monitoring der Chunk-Verteilung
Hinweise:
---------
- Nutzt synchrones assemble_chunks (kann async sein)
- Heuristik für Oversize: > 600 Tokens
- Prüft nur strukturelle Integrität, keine semantische Qualität
Aufruf:
-------
python3 -m scripts.audit_chunks --vault ./vault
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.0.0: Initial Release
"""
from __future__ import annotations
import argparse, os, json, glob, statistics as stats
from app.core.parser import read_markdown, normalize_frontmatter, validate_required_frontmatter
+56 -24
View File
@@ -1,34 +1,66 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Script: audit_edges_vs_expectations.py — Prüfe Kanten in Qdrant gegen Vault-Erwartungen
Version: 1.0.0
Datum: 2025-09-09
FILE: scripts/audit_edges_vs_expectations.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck
-----
- Liest Edges/Chunks/Notes aus Qdrant.
- Ermittelt erwartete Kanten-Anzahlen aus dem Vault:
* belongs_to : sollte == #Chunks
* next / prev : je Note (#Chunks_in_Note - 1)
* references : Summe aller Chunk-Wikilinks
* backlink : Summe einzigartiger Wikilinks pro Note (Note-Level)
- Vergleicht IST vs. SOLL und meldet Abweichungen.
ENV/Qdrant
----------
QDRANT_URL, QDRANT_API_KEY (optional), COLLECTION_PREFIX (Default: mindnet)
Aufrufe
Zweck:
-------
# Gesamtaudit
python3 -m scripts.audit_edges_vs_expectations --vault ./test_vault
Prüft Edge-Anzahlen in Qdrant gegen erwartete Werte aus dem Vault.
Validiert strukturelle Integrität des Graphen.
# Mit anderem Prefix
python3 -m scripts.audit_edges_vs_expectations --vault ./test_vault --prefix mindnet_dev
Funktionsweise:
---------------
1. Liest Edges/Chunks/Notes aus Qdrant
2. Ermittelt erwartete Edge-Anzahlen aus Vault:
- belongs_to: sollte == #Chunks pro Note
- next/prev: je Note (#Chunks - 1)
- references: Summe aller Chunk-Wikilinks
- backlink: Summe einzigartiger Wikilinks (Note-Level)
3. Vergleicht IST vs. SOLL
4. Meldet Abweichungen
# Details anzeigen
python3 -m scripts.audit_edges_vs_expectations --vault ./test_vault --details
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON mit Vergleichs-Ergebnissen
* expected: Erwartete Edge-Anzahlen
* actual: Tatsächliche Edge-Anzahlen
* discrepancies: Abweichungen
* per_note: Details pro Note (mit --details)
- Exit-Code 0: Erfolgreich
Verwendung:
-----------
- Validierung nach Importen
- Debugging von Edge-Problemen
- Qualitätskontrolle
Hinweise:
---------
- Prüft strukturelle, nicht semantische Korrektheit
- Kann bei großen Vaults langsam sein
Aufruf:
-------
python3 -m scripts.audit_edges_vs_expectations --vault ./vault
python3 -m scripts.audit_edges_vs_expectations --vault ./vault --prefix mindnet_dev --details
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
--prefix TEXT Collection-Präfix (Default: mindnet)
--details Zeigt Details pro Note
Umgebungsvariablen:
-------------------
QDRANT_URL, QDRANT_API_KEY (optional), COLLECTION_PREFIX
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.0.0 (2025-09-09): Initial Release
"""
from __future__ import annotations
+48 -25
View File
@@ -1,38 +1,61 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Name: scripts/audit_vault_vs_qdrant.py
Version: v1.0.0 (2025-09-05)
Kurzbeschreibung:
Prüft die Konsistenz zwischen Obsidian-Vault und Qdrant:
- Zählt Markdown-Dateien mit gültiger Frontmatter (title, id, type, status, created).
- Zählt Wikilink-Vorkommen im Vault (regex wie in derive_edges.py).
- Liest Zählungen aus Qdrant (Notes/Chunks/Edges je kind).
- Vergleicht erwartete Wikilink-Anzahl (Vault) vs. tatsächlich importierte Edges (Qdrant).
- Listet Auffälligkeiten pro Note (z. B. Wikilinks im Vault, aber keine references in Qdrant).
FILE: scripts/audit_vault_vs_qdrant.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Aufruf (aus Projekt-Root, im venv):
python3 -m scripts.audit_vault_vs_qdrant --vault ./vault --prefix mindnet
Zweck:
-------
Prüft Konsistenz zwischen Vault und Qdrant.
Vergleicht erwartete vs. tatsächliche Edge-Anzahlen.
Parameter:
--vault Pfad zum Vault (z. B. ./vault)
--prefix Collection-Prefix in Qdrant (Default: mindnet)
--limit Max. Punkte pro Scroll-Seite aus Qdrant (Default: 1000)
Funktionsweise:
---------------
1. Scannt Vault:
- Zählt Markdown-Dateien mit gültiger Frontmatter
- Zählt Wikilink-Vorkommen (regex wie in derive_edges.py)
2. Liest Qdrant:
- Zählt Notes/Chunks/Edges
- Gruppiert Edges nach kind
3. Vergleicht:
- Erwartete Wikilink-Anzahl (Vault) vs. references (Qdrant)
- Listet Auffälligkeiten pro Note
Voraussetzungen:
- Aktives Python venv mit installiertem qdrant-client.
- Zugriff auf Qdrant per ENV (QDRANT_URL, QDRANT_API_KEY optional).
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON mit Vergleichs-Ergebnissen
* vault_stats: Zählungen aus Vault
* qdrant_stats: Zählungen aus Qdrant
* discrepancies: Abweichungen und Auffälligkeiten
- Exit-Code 0: Erfolgreich
Verwendung:
-----------
- Konsistenz-Check nach Importen
- Validierung der Edge-Erzeugung
- Debugging von fehlenden Links
Hinweise:
- Der Wikilink-Regex entspricht dem in app/core/derive_edges.py verwendeten Muster. (Quelle: derive_edges.py) # :contentReference[oaicite:3]{index=3}
- Pflicht-Frontmatter wird wie in app/core/parser.py geprüft. (Quelle: parser.py) # :contentReference[oaicite:4]{index=4}
- Collection-Namen & 1D-Edge-Vektoren folgen app/core/qdrant.py / qdrant_points.py. (Quellen: qdrant.py, qdrant_points.py) #
---------
- Wikilink-Regex entspricht derive_edges.py
- Prüft strukturelle, nicht semantische Korrektheit
Changelog:
v1.0.0: Erste Version.
Aufruf:
-------
python3 -m scripts.audit_vault_vs_qdrant --vault ./vault --prefix mindnet
Autor:
mindnet – Datenimporte & Sync
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
--prefix TEXT Collection-Präfix (Default: mindnet)
--limit INT Max. Punkte pro Scroll-Seite (Default: 1000)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.0.0 (2025-09-05): Initial Release
"""
from __future__ import annotations
import argparse, os, glob, re, json
+61 -3
View File
@@ -1,12 +1,70 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
FILE: scripts/backfill_edges.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Füllt fehlende Edges nach, indem es Wikilinks aus dem Vault extrahiert
und in Qdrant schreibt. Nützlich nach Migrationen oder wenn Edges verloren gingen.
Funktionsweise:
---------------
1. Scannt alle Markdown-Dateien im Vault
2. Für jede Datei:
- Erstellt Note-Stub (minimaler Payload)
- Erstellt einen Chunk mit dem gesamten Body
- Extrahiert Wikilinks via derive_wikilink_edges
3. Baut Lookup-Index (Titel/Alias -> note_id)
4. Löst Wikilinks auf und erzeugt Edges
5. Schreibt Edges in Qdrant
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON mit Statistiken
* notes_scanned: Anzahl verarbeiteter Notizen
* edges_upserted: Anzahl geschriebener Edges
- Exit-Code 0: Erfolgreich
Verwendung:
-----------
- Nach Migrationen oder Datenverlust
- Wenn Edges fehlen oder unvollständig sind
- Zur Reparatur des Graphen
Hinweise:
---------
- Überschreibt existierende Edges (kein Merge)
- Nutzt vereinfachtes Chunking (1 Chunk = gesamter Body)
- Erzeugt nur Wikilink-Edges, keine anderen Edge-Typen
Aufruf:
-------
python3 -m scripts.backfill_edges --vault ./vault
python3 -m scripts.backfill_edges --vault ./vault --exclude /.obsidian/ /_backup/
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
--exclude PATH Pfade zum Ausschließen (Default: /.obsidian/, /_backup_frontmatter/)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.0.0: Initial Release
"""
from __future__ import annotations
import argparse, glob, json, os
from typing import List, Tuple
from app.core.parser import read_markdown # gibt je nach Implementierung ein Objekt ODER ein (fm, body)-Tuple
from app.core.qdrant import QdrantConfig, get_client, ensure_collections
from app.core.qdrant_points import points_for_edges, upsert_batch
from app.core.derive_edges import build_note_index, derive_wikilink_edges
from app.core.database.qdrant import QdrantConfig, get_client, ensure_collections
from app.core.database.qdrant_points import points_for_edges, upsert_batch
# TODO: build_note_index und derive_wikilink_edges müssen noch implementiert werden
# from app.core.graph.graph_derive_edges import build_note_index, derive_wikilink_edges
def _coerce_parsed(note_or_tuple):
+92 -5
View File
@@ -1,3 +1,67 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
FILE: scripts/debug_edge_loss.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active (Debug-Tool)
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Debug-Tool zur Analyse von Edge-Verlust-Problemen bei der Chunk-Verarbeitung.
Hilft zu verstehen, warum bestimmte Edges nicht erkannt oder verloren gehen.
Funktionsweise:
---------------
1. Analysiert eine einzelne Markdown-Datei
2. Führt zwei Analyseschritte durch:
a) Pre-Scan: Extrahiert alle Edge-Kandidaten aus dem rohen Text
- Wikilinks
- Typed Relations
- Callout Relations
b) Chunk-Analyse:
- Erstellt Chunks mit konfigurierbarem Profil
- Prüft, welche Edges in jedem Chunk gefunden werden
- Vergleicht mit Pre-Scan-Ergebnissen
3. Gibt detaillierte Analyse pro Chunk aus
Ergebnis-Interpretation:
------------------------
- [1] Globale Kandidaten: Alle Edge-Kandidaten, die im Text vorhanden sind
- [2] Chunk-Struktur: Für jeden Chunk:
* Section-Pfad
* Text-Snippet
* Gefundene explizite Kanten (callout:edge, inline:rel)
* Warnung, falls Callout im Text vorhanden, aber nicht erkannt
Verwendung:
-----------
- Debugging von Edge-Verlust bei Chunk-Grenzen
- Validierung der Edge-Extraktion in verschiedenen Chunk-Kontexten
- Analyse von Problemen mit Callout-Erkennung
Hinweise:
---------
- Asynchrones Skript (nutzt assemble_chunks async API)
- Konfigurierbares Chunking-Profil (Standard: sliding_window, 400/600 chars)
- Smart Edge Allocation ist standardmäßig deaktiviert für klare Analyse
Aufruf:
-------
python3 scripts/debug_edge_loss.py [PFAD_ZUR_DATEI.md]
Parameter:
----------
Keine CLI-Parameter. Dateipfad als erstes Argument oder Standard-Pfad.
Änderungen:
-----------
v2.1.0 (2025-12-15): Kompatibilität mit WP-14 Modularisierung
- Entfernt: _extract_all_edges_from_md (nicht mehr vorhanden)
- Ersetzt durch: extract_wikilinks, extract_typed_relations, extract_callout_relations
- Chunk-Payload-Struktur angepasst (window, type hinzugefügt)
v1.0.0: Erster Release
"""
import asyncio
import os
import sys
@@ -6,8 +70,10 @@ from pathlib import Path
# Pfad-Setup
sys.path.insert(0, os.path.abspath("."))
from app.core.chunking import assemble_chunks, _extract_all_edges_from_md
from app.core.derive_edges import build_edges_for_note
from app.core.chunking import assemble_chunks
from app.core.graph.graph_derive_edges import build_edges_for_note
from app.core.parser import extract_wikilinks
from app.core.graph.graph_extractors import extract_typed_relations, extract_callout_relations
# Mock für Settings, falls nötig
os.environ["MINDNET_LLM_MODEL"] = "phi3:mini"
@@ -19,9 +85,25 @@ async def analyze_file(file_path: str):
text = f.read()
# 1. Globale Kandidaten (Was sieht der Pre-Scan?)
# Wir simulieren den Aufruf, den der Chunker macht
# Wir extrahieren alle Edge-Kandidaten aus dem Text
note_id = Path(file_path).stem
candidates = _extract_all_edges_from_md(text, note_id, "concept")
candidates = []
# Wikilinks extrahieren
wikilinks = extract_wikilinks(text)
for wl in wikilinks:
candidates.append(f"wikilink:{wl}")
# Typed Relations extrahieren
typed_rels, _ = extract_typed_relations(text)
for kind, target in typed_rels:
candidates.append(f"typed:{kind}:{target}")
# Callout Relations extrahieren
callout_rels, _ = extract_callout_relations(text)
for kind, target in callout_rels:
candidates.append(f"callout:{kind}:{target}")
print(f"\n[1] Globale Kandidaten (Pre-Scan):")
for c in candidates:
print(f" - {c}")
@@ -45,7 +127,12 @@ async def analyze_file(file_path: str):
# Was findet derive_edges in diesem rohen Chunk?
# Wir simulieren das Payload-Dict, das derive_edges erwartet
chunk_pl = {"text": chunk.text, "window": chunk.window, "chunk_id": chunk.id}
chunk_pl = {
"text": chunk.text,
"window": chunk.window or chunk.text,
"chunk_id": chunk.id,
"type": "concept"
}
edges = build_edges_for_note(note_id, [chunk_pl])
found_explicitly = [f"{e['kind']}:{e.get('target_id')}" for e in edges if e['rule_id'] in ['callout:edge', 'inline:rel']]
+52 -6
View File
@@ -1,15 +1,62 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/debug_note_payload.py
Zeigt, welche app.core.note_payload geladen wird, ruft make_note_payload auf
und druckt Typ/Preview der Rückgabe.
FILE: scripts/debug_note_payload.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active (Debug-Tool)
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Debug-Tool zur Analyse der Note-Payload-Erzeugung.
Zeigt, welches Modul geladen wird und die erzeugte Payload-Struktur.
Funktionsweise:
---------------
1. Lädt Note-Payload-Modul
2. Liest Markdown-Datei
3. Ruft make_note_payload auf
4. Zeigt Modul-Pfad, Rückgabe-Typ und Payload-Inhalt
Ergebnis-Interpretation:
------------------------
- Ausgabe: Debug-Informationen
* module_path: Pfad zum geladenen Modul
* return_type: Typ der Rückgabe
* keys: Liste der Payload-Keys (falls Dict)
* JSON: Vollständige Payload (falls Dict)
Verwendung:
-----------
- Debugging von Payload-Erzeugungsproblemen
- Validierung der Modul-Ladung
- Analyse der Payload-Struktur
Hinweise:
---------
- Nutzt app.core.ingestion.ingestion_note_payload (nicht mehr app.core.note_payload)
- Zeigt vollständige Payload-Struktur
Aufruf:
python3 -m scripts.debug_note_payload --file ./test_vault/40_concepts/concept-alpha.md --vault-root ./test_vault
-------
python3 -m scripts.debug_note_payload --file ./vault/note.md --vault-root ./vault
Parameter:
----------
--file PATH Pfad zur Markdown-Datei (erforderlich)
--vault-root PATH Vault-Root für relative Pfade (optional)
--hash-mode MODE Hash-Modus (optional)
--hash-normalize N Hash-Normalisierung (optional)
--hash-source SRC Hash-Quelle (optional)
Änderungen:
-----------
v2.1.0 (2025-12-15): Kompatibilität mit WP-14 Modularisierung
- Geändert: app.core.note_payload → app.core.ingestion.ingestion_note_payload
v1.0.0: Initial Release
"""
import argparse, json, os, pprint
from app.core import note_payload as np
from app.core.ingestion import ingestion_note_payload as np
from app.core.parser import read_markdown
def main():
@@ -24,7 +71,6 @@ def main():
print("module_path:", getattr(np, "__file__", "<unknown>"))
parsed = read_markdown(args.file)
res = np.make_note_payload(parsed, vault_root=args.vault_root,
hash_mode=args.hash_mode,
hash_normalize=args.hash_normalize,
hash_source=args.hash_source,
file_path=args.file)
+48 -7
View File
@@ -1,18 +1,59 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/debug_qdrant_state.py
Zeigt Prefix, Collections und einfache Counts (notes/chunks/edges) + sample note_ids.
FILE: scripts/debug_qdrant_state.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active (Debug-Tool)
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Zeigt schnelle Übersicht über den Qdrant-Zustand.
Gibt Prefix, Collections, Punkt-Anzahlen und Beispiel-IDs aus.
Funktionsweise:
---------------
1. Verbindet mit Qdrant
2. Ermittelt Collections für das Präfix
3. Zählt Points in jeder Collection
4. Extrahiert Beispiel-IDs (erste 5)
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON mit Zustands-Übersicht
* prefix: Collection-Präfix
* collections: Namen der Collections
* counts: Punkt-Anzahlen pro Collection
* samples: Beispiel-IDs pro Collection
Verwendung:
-----------
- Schnelle Status-Prüfung
- Debugging von Verbindungsproblemen
- Validierung der Collection-Struktur
Hinweise:
---------
- Nutzt count() für exakte Zählung (falls verfügbar)
- Fallback auf scroll() bei Problemen
Aufruf:
export COLLECTION_PREFIX="mindnet"
python3 -m scripts.debug_qdrant_state
# oder:
python3 -m scripts.debug_qdrant_state --prefix mindnet
-------
python3 -m scripts.debug_qdrant_state
python3 -m scripts.debug_qdrant_state --prefix mindnet_dev
Parameter:
----------
--prefix TEXT Collection-Präfix (Default: ENV COLLECTION_PREFIX oder mindnet)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.0.0: Initial Release
"""
from __future__ import annotations
import argparse, os, json
from app.core.qdrant import QdrantConfig, get_client
from app.core.database.qdrant import QdrantConfig, get_client
def count_points(client, collection: str) -> int:
try:
+50 -7
View File
@@ -1,13 +1,56 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/diag_payload_indexes.py (compat v1.2)
FILE: scripts/diag_payload_indexes.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zeigt payload_schema je Collection; kompatibel mit älteren qdrant-client Versionen.
Strategie (in dieser Reihenfolge):
1) openapi_client.collections_api.get_collection(..., with_payload_schema=True)
2) client.get_collection(...)
3) HTTP GET /collections/{name}?with_payload_schema=true
Zweck:
-------
Zeigt das Payload-Schema (Indizes) für alle Collections eines Präfixes.
Nützlich zur Diagnose von Index-Problemen oder Validierung der Schema-Struktur.
Funktionsweise:
---------------
1. Ermittelt Collections für das Präfix (notes, chunks, edges)
2. Für jede Collection:
- Versucht Payload-Schema über verschiedene Methoden zu laden:
* qdrant-client API (get_collection)
* HTTP GET direkt (Fallback)
- Zeigt Schema als JSON
3. Gibt Schema-Übersicht aus
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON pro Collection mit payload_schema
- Zeigt vorhandene Indizes (keyword, text) und deren Konfiguration
- Exit-Code 0: Erfolgreich
Verwendung:
-----------
- Diagnose von Index-Problemen
- Validierung nach ensure_payload_indexes
- Dokumentation der Schema-Struktur
Hinweise:
---------
- Kompatibel mit verschiedenen qdrant-client Versionen
- Nutzt Fallback-Strategie für maximale Kompatibilität
Aufruf:
-------
python3 -m scripts.diag_payload_indexes --prefix mindnet
Parameter:
----------
--prefix TEXT Collection-Präfix (Default: ENV COLLECTION_PREFIX oder mindnet)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.2.0: Kompatibilität mit verschiedenen qdrant-client Versionen
v1.0.0: Initial Release
"""
from __future__ import annotations
@@ -17,7 +60,7 @@ import urllib.request
import urllib.error
from typing import Any, Dict
from app.core.qdrant import QdrantConfig, get_client, collection_names
from app.core.database.qdrant import QdrantConfig, get_client, collection_names
def _safe_model_dump(obj: Any) -> Dict[str, Any]:
+54
View File
@@ -1,4 +1,58 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
FILE: scripts/dump_note_chunks.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Gibt die Chunks einer bestimmten Note in lesbarer Form aus.
Nützlich zur Analyse der Chunk-Struktur und -Inhalte.
Funktionsweise:
---------------
1. Sucht Note nach note-id im Vault
2. Erzeugt Chunks via assemble_chunks
3. Gibt Chunks formatiert aus:
- Chunk-ID, Token-Anzahl, Section-Pfad
- Vollständiger Chunk-Text
Ergebnis-Interpretation:
------------------------
- Ausgabe: Formatierter Text
* Header: "# Titel (note-id) — X chunks"
* Pro Chunk: "--- chunk_id | tokens | section_path ---"
* Gefolgt vom Chunk-Text
- Exit-Code 0: Erfolgreich
- Fehlermeldung, wenn Note nicht gefunden
Verwendung:
-----------
- Analyse der Chunk-Struktur einer spezifischen Note
- Debugging von Chunking-Problemen
- Validierung der Chunk-Inhalte
Hinweise:
---------
- Nutzt synchrones assemble_chunks (kann async sein)
- Gibt nur erste gefundene Note aus (bei Duplikaten)
Aufruf:
-------
python3 -m scripts.dump_note_chunks --vault ./vault --note-id my-note-id
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
--note-id ID Note-ID zum Dumpen (erforderlich)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.0.0: Initial Release
"""
from __future__ import annotations
import argparse, os, glob
from app.core.parser import read_markdown, normalize_frontmatter, validate_required_frontmatter
+63 -15
View File
@@ -1,22 +1,70 @@
#!/usr/bin/env python3
# scripts/edges_dryrun.py
# -*- coding: utf-8 -*-
"""
Dry-Run: Erzeuge Edges aus einem Vault **ohne** Qdrant-Upsert.
- Liest Markdown mit YAML-Frontmatter
- Chunking: einfacher Absatz-Chunker (Index + text)
- Kanten: nutzt app.core.edges.build_edges_for_note()
- Ausgabe: JSON pro Note mit Edge-Counts und 3 Beispiel-Payloads
FILE: scripts/edges_dryrun.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Simuliert die Edge-Erzeugung aus Markdown-Dateien ohne Datenbank-Upsert.
Nützlich zur Analyse, welche Kanten aus einem Vault generiert würden.
Funktionsweise:
---------------
1. Scannt alle .md-Dateien im Vault
2. Für jede Datei:
- Parst Markdown mit Frontmatter
- Erstellt einfache Absatz-basierte Chunks (vereinfachtes Chunking)
- Extrahiert Edge-Kandidaten via build_edges_for_note():
* Wikilinks [[...]]
* Typed Relations [[rel:KIND|Target]]
* Callout Relations [!edge] KIND: [[Target]]
* Struktur-Kanten (belongs_to, next, prev)
- Zählt Edges nach Typ (kind/relation)
3. Gibt JSON-Report aus mit Edge-Statistiken pro Note
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON-Array mit einem Objekt pro Note
- Jedes Objekt enthält:
* path: Dateipfad
* note_id: Note-Identifier
* type: Note-Typ
* chunks: Anzahl der Chunks
* edges_total: Gesamtanzahl der Edges
* edges_by_kind: Dictionary mit Edge-Anzahl pro Typ
* samples: Erste 3 Edges als Beispiele
Verwendung:
-----------
- Analyse der Graph-Struktur vor dem Import
- Debugging von fehlenden oder unerwarteten Edges
- Validierung der Edge-Extraktion-Logik
Hinweise:
---------
- Verwendet vereinfachtes Chunking (Absatz-basiert), nicht das vollständige Chunking-System
- Edge-Extraktion entspricht der Produktions-Logik (app.core.derive_edges)
- Keine Datenbank-Operationen, rein analytisch
Aufruf:
python3 -m scripts.edges_dryrun --vault ./vault
-------
python3 -m scripts.edges_dryrun --vault ./vault
python3 -m scripts.edges_dryrun --vault ./vault --include-note-scope-refs
Optional:
--include-note-scope-refs # auch Frontmatter-Links (links[].target_id) als Note-Scope-Referenzen
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
--include-note-scope-refs Berücksichtigt auch Frontmatter-Links (links[].target_id)
Voraussetzungen:
- app/core/parser.py (read_markdown, normalize_frontmatter)
- app/core/edges.py (dieses Modul forwardet zur v2-Implementierung)
Änderungen:
-----------
v2.1.0 (2025-12-15): Kompatibilität mit WP-14 Modularisierung
- Geändert: app.core.edges → app.core.derive_edges
- Parameter korrigiert: chunk_payloads → chunks, note_level_refs → note_level_references
v1.0.0: Erster Release
"""
from __future__ import annotations
@@ -28,7 +76,7 @@ from pathlib import Path
from typing import Dict, List, Optional
from app.core.parser import read_markdown, normalize_frontmatter
from app.core.edges import build_edges_for_note
from app.core.graph.graph_derive_edges import build_edges_for_note
def _iter_markdown(vault: str):
for p in Path(vault).rglob("*.md"):
@@ -83,8 +131,8 @@ def main():
edges = build_edges_for_note(
note_id=note_id,
chunk_payloads=chunks,
note_level_refs=note_refs,
chunks=chunks,
note_level_references=note_refs,
include_note_scope_refs=include_note_scope,
)
kinds = {}
+58 -13
View File
@@ -1,19 +1,64 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/edges_full_check.py
Zählt und validiert Kanten in Qdrant. Erkennt folgende Rule-Gruppen:
- explicit_total: rule_id startswith "explicit:" (z.B. explicit:wikilink, explicit:note_scope)
- callout_total: rule_id == "callout:edge"
- inline_total: rule_id startswith "inline:" (z.B. inline:rel)
- defaults_total: rule_id startswith "edge_defaults:"
- structure: rule_id in {"structure:belongs_to","structure:order"}
FILE: scripts/edges_full_check.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Gibt zusätzlich:
- edges_by_kind (aggregiert)
- notes/chunks/edges Anzahlen
- multi_callout_detected: True, falls ein Chunk mehrere Callout-Ziele der gleichen Relation enthält
- per_note_checks: belongs_to == chunks, next == prev == (chunks-1)
Zweck:
-------
Umfassende Validierung der Edge-Struktur in Qdrant.
Analysiert Edge-Typen, Rule-Gruppen und strukturelle Integrität.
Funktionsweise:
---------------
1. Lädt alle Edges aus {prefix}_edges
2. Gruppiert Edges nach rule_id:
- explicit: rule_id startswith "explicit:" (wikilink, note_scope)
- callout: rule_id == "callout:edge"
- inline: rule_id startswith "inline:" (rel)
- defaults: rule_id startswith "edge_defaults:"
- structure: rule_id in {"structure:belongs_to", "structure:order"}
3. Prüft strukturelle Integrität:
- belongs_to == chunks pro Note
- next == prev == (chunks-1) pro Note
- Multi-Callout-Erkennung
4. Aggregiert Statistiken
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON mit umfassender Analyse
* counts: notes/chunks/edges Anzahlen
* edges_by_kind: Aggregierte Edge-Anzahl pro Typ
* rule_groups: Zählung nach Rule-Gruppen
* per_note_checks: Strukturelle Validierung pro Note
* multi_callout_detected: Boolean
- Exit-Code 0: Erfolgreich
Verwendung:
-----------
- Umfassende Graph-Analyse
- Validierung nach größeren Änderungen
- Debugging von Edge-Problemen
Hinweise:
---------
- Kann bei großen Graphen langsam sein
- Prüft strukturelle, nicht semantische Korrektheit
Aufruf:
-------
python3 -m scripts.edges_full_check --prefix mindnet
Parameter:
----------
--prefix TEXT Collection-Präfix (Default: ENV COLLECTION_PREFIX oder mindnet)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.0.0: Initial Release
"""
from __future__ import annotations
@@ -22,7 +67,7 @@ import json
from collections import Counter, defaultdict
from typing import Dict, Any, List, Tuple
from app.core.qdrant import QdrantConfig, get_client
from app.core.database.qdrant import QdrantConfig, get_client
from qdrant_client.http import models as rest
+64 -30
View File
@@ -1,39 +1,74 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Script: scripts/export_markdown.py — Qdrant → Markdown (Vault)
Version: 1.4.1
Datum: 2025-09-10
FILE: scripts/export_markdown.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Funktion
--------
Exportiert Notes (Frontmatter + Body) aus Qdrant in einen Zielordner. Der Body wird
bevorzugt aus dem Feld `fulltext` rekonstruiert; falls leer/nicht vorhanden, aus Chunks
(Sortierung: seq → chunk_index → Nummer in chunk_id). Pfade werden **relativ** geschrieben.
Zweck:
-------
Exportiert Notes (Frontmatter + Body) aus Qdrant zurück in Markdown-Dateien.
Nützlich für Backup, Migration oder Notfall-Wiederherstellung.
Optionen
--------
--out PATH Zielordner (erforderlich)
--prefix TEXT Collection-Prefix (CLI überschreibt ENV COLLECTION_PREFIX)
--note-id ID Nur eine Note exportieren
--overwrite Existierende Dateien überschreiben
--include-edges MODE none|yaml|footer (Default: none)
--flatten-paths Alle Dateien flach schreiben; Originalpfad in FM: orig_path
Funktionsweise:
---------------
1. Liest alle Notes aus Qdrant (Collection: {prefix}_notes)
2. Für jede Note:
- Rekonstruiert Frontmatter aus Payload-Feldern
- Rekonstruiert Body:
* Primär: aus `fulltext` Feld (falls vorhanden)
* Fallback: aus Chunks (sortiert nach seq → chunk_index → chunk_id)
- Optional: Fügt Edges als Links hinzu (yaml/footer)
3. Schreibt Markdown-Dateien mit relativen Pfaden
ENV
---
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON pro Datei mit note_id, path, decision (write/skip-exists)
- Abschluss: "Done. Exported notes: X"
- Exit-Code 0: Erfolgreich
Verwendung:
-----------
- Backup vor größeren Änderungen
- Migration zwischen Instanzen
- Notfall-Wiederherstellung bei Vault-Verlust
- Analyse der in Qdrant gespeicherten Daten
Hinweise:
---------
- Pfade werden relativ geschrieben (wie im Original-Vault)
- --flatten-paths: Alle Dateien in einen Ordner (orig_path in Frontmatter)
- Body-Rekonstruktion aus Chunks kann bei sehr langen Dokumenten unvollständig sein
- Edge-Export optional (none/yaml/footer)
Aufruf:
-------
python3 -m scripts.export_markdown --out ./_exportVault
python3 -m scripts.export_markdown --out ./_exportVault --note-id concept-alpha --include-edges yaml
python3 -m scripts.export_markdown --out ./_exportVault --flatten-paths --overwrite
Parameter:
----------
--out PATH Zielordner für exportierte Markdown-Dateien (erforderlich)
--prefix TEXT Collection-Präfix (überschreibt ENV COLLECTION_PREFIX)
--note-id ID Nur eine bestimmte Note-ID exportieren (optional)
--overwrite Existierende Dateien überschreiben (sonst skip)
--include-edges MODE none|yaml|footer (Default: none)
- none: Keine Edges
- yaml: Als YAML-Feld 'references' im Frontmatter
- footer: Als Markdown-Links am Ende
--flatten-paths Alle Dateien flach schreiben (orig_path in Frontmatter)
Umgebungsvariablen:
-------------------
COLLECTION_PREFIX, QDRANT_URL | QDRANT_HOST/QDRANT_PORT | QDRANT_API_KEY
Beispiele
---------
export COLLECTION_PREFIX="mindnet"
python3 -m scripts.export_markdown --out ./_exportVault
# Nur eine Note, Edges als YAML-Feld 'references'
python3 -m scripts.export_markdown --out ./_exportVault --note-id concept-alpha --include-edges yaml
# Flach schreiben mit Überschreiben
python3 -m scripts.export_markdown --out ./_exportVault --flatten-paths --overwrite
Änderungen:
-----------
v2.1.0 (2025-12-15): Kompatibilität mit WP-14 Modularisierung
- Aktualisiert: Import-Pfade für neue Struktur
v1.4.1 (2025-09-10): Initial Release
"""
from __future__ import annotations
@@ -45,8 +80,7 @@ from typing import Dict, List, Optional, Tuple, Any
import yaml
from qdrant_client.http import models as rest
from app.core.qdrant import QdrantConfig, get_client
from app.core.qdrant import ensure_collections # safety
from app.core.database.qdrant import QdrantConfig, get_client, ensure_collections
# ---------------------------------------------------------------------
# Helpers
+65 -1
View File
@@ -1,4 +1,68 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
FILE: scripts/fix_frontmatter.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Repariert oder ergänzt fehlende Frontmatter-Felder in Markdown-Dateien.
Erzeugt stabile IDs, erkennt Typen und erstellt vollständige Frontmatter-Struktur.
Funktionsweise:
---------------
1. Scannt alle Markdown-Dateien im Vault
2. Für jede Datei:
- Liest vorhandenes Frontmatter
- Erkennt fehlende Felder (id, title, type, created)
- Generiert fehlende Werte:
* id: Stabile ID aus Pfad, Titel und Datum
* title: Aus H1, Dateiname oder "Untitled"
* type: Aus Pfad/Tags (journal, task, project, etc.)
* created: Aus Dateiname oder mtime
- Validiert Payload (optional)
- Schreibt korrigiertes Frontmatter zurück
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON pro Datei mit Änderungen
* path: Dateipfad
* changes: Dict mit alten/neuen Werten
* backup_path: Pfad zur Backup-Datei (falls --backup)
- Exit-Code 0: Erfolgreich
Verwendung:
-----------
- Migration von Legacy-Vaults ohne Frontmatter
- Reparatur beschädigter Frontmatter
- Standardisierung von Frontmatter-Strukturen
Hinweise:
---------
- Erstellt Backups vor Änderungen (mit --backup)
- Idempotent: Überspringt bereits vollständige Frontmatter
- Nutzt Heuristiken für Typ-Erkennung (Pfad/Tags)
Aufruf:
-------
python3 -m scripts.fix_frontmatter --vault ./vault --apply
python3 -m scripts.fix_frontmatter --vault ./vault --backup --apply
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
--backup Erstellt Backup-Dateien vor Änderungen
--apply Führt tatsächliche Änderungen durch (sonst Dry-Run)
--validate Validiert Note-Payload nach Fix
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
- Hinweis: validate_note_payload existiert nicht mehr (wird entfernt)
v1.0.0: Initial Release
"""
from __future__ import annotations
import argparse, os, re, sys, json, shutil, time, hashlib
from dataclasses import dataclass
@@ -6,7 +70,7 @@ from typing import Dict, Tuple, Optional, List
from slugify import slugify
from app.core.parser import read_markdown, normalize_frontmatter
from app.core.parser import FRONTMATTER_RE # für Re-Inject
from app.core.validate_note import validate_note_payload
# NOTE: validate_note_payload existiert nicht mehr - entfernt
from app.core.ingestion.ingestion_note_payload import make_note_payload
DATE_IN_NAME = re.compile(r"(?P<y>\d{4})[-_\.]?(?P<m>\d{2})[-_\.]?(?P<d>\d{2})")
+70 -47
View File
@@ -1,50 +1,73 @@
#!/usr/bin/env python3
# scripts/gc_qdrant_after_vault_scan.py
# Version: 1.0.0 (2025-09-05)
#
# Zweck
# -----
# Garbage-Collector für Qdrant: löscht Einträge (Edges, Chunks, Notes), deren Note-ID
# nicht mehr im Obsidian-Vault vorhanden ist. So bleiben Vektorindex/Graph mit dem Vault konsistent.
#
# Aufrufparameter
# ---------------
# --vault PATH Pfad zum Obsidian-Vault (z. B. ./vault) [erforderlich]
# --mode {edges,content,all}
# edges -> nur Kanten mit source_id/target_id ∉ Vault-Notes löschen
# content -> Chunks & Notes löschen, deren note_id ∉ Vault-Notes (keine Edges)
# all -> zuerst edges, dann content
# --prefix PREFIX Collection-Präfix (Default: aus ENV COLLECTION_PREFIX oder "mindnet")
# --apply Ohne diesen Schalter: Dry-Run (nur Vorschau). Mit Schalter: ausführen.
# --yes Sicherheitsabfrage überspringen (non-interaktiv)
# --batch-size N Größe für In-Filter (Default: 1000)
#
# Hinweise
# --------
# - Benötigt funktionierendes Python-venv mit allen Abhängigkeiten von mindnet (qdrant-client usw.).
# - Läuft gegen die drei Collections {prefix}_notes, {prefix}_chunks, {prefix}_edges (keine anderen Projekte).
# - Nutzt OR-Filter (Filter.should) korrekt, keine minimum_should (Pydantic v2 lässt die Option nicht zu).
#
# Änderungen ggü. vorher
# ----------------------
# - Neu: eigenes GC-Tool; berührt ausschließlich das übergebene Projekt-Präfix.
# - Sichere Dry-Run-Vorschau mit Zählung pro Collection; interaktive Bestätigung.
# - Löscht Edges mittels Filter auf (source_id ∈ MISSING) ODER (target_id ∈ MISSING).
# - Löscht Chunks/Notes mittels Filter auf note_id ∈ MISSING.
#
# Beispiele
# ---------
# DRY RUN: python3 -m scripts.gc_qdrant_after_vault_scan --vault ./vault --mode all
# APPLY: python3 -m scripts.gc_qdrant_after_vault_scan --vault ./vault --mode all --apply
# CI-Modus: python3 -m scripts.gc_qdrant_after_vault_scan --vault ./vault --mode edges --apply --yes
#
# Kompatibilität / Kontext
# ------------------------
# - Frontmatter-Validierung & Parsing wie im Projekt (parser.read_markdown, validate_required_frontmatter). :contentReference[oaicite:0]{index=0}
# - Note-Payload-Schema (u. a. note_id, hash_fulltext) wie spezifiziert. :contentReference[oaicite:1]{index=1}
# - Collection-Namen & Anlage-Logik über app.core.qdrant (notes/chunks = dim, edges = 1D). :contentReference[oaicite:2]{index=2}
# - Edges nutzen Felder source_id/target_id; Chunks/Notes tragen note_id in payload. :contentReference[oaicite:3]{index=3} :contentReference[oaicite:4]{index=4}
#
# -*- coding: utf-8 -*-
"""
FILE: scripts/gc_qdrant_after_vault_scan.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Garbage-Collector für Qdrant: löscht Einträge, deren Note-ID nicht mehr
im Vault vorhanden ist. Hält Vektorindex/Graph mit dem Vault konsistent.
Funktionsweise:
---------------
1. Scannt Vault und sammelt alle note_ids
2. Lädt note_ids aus Qdrant
3. Berechnet Differenz (verwaiste IDs)
4. Löscht verwaiste Einträge:
- mode=edges: Nur Edges mit source_id/target_id ∉ Vault
- mode=content: Chunks & Notes mit note_id ∉ Vault
- mode=all: Zuerst edges, dann content
5. Nutzt Batch-Filter für effiziente Löschung
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON mit Preview und Statistiken
* mode: DRY-RUN oder APPLY
* vault_note_ids: Anzahl Notizen im Vault
* qdrant_note_ids: Anzahl Notizen in Qdrant
* orphans: Anzahl verwaister Notizen
* deleted: Anzahl gelöschter Einträge (nach --apply)
- Exit-Code 0: Erfolgreich
Verwendung:
-----------
- Regelmäßige Wartung nach Vault-Bereinigung
- Konsistenz-Check zwischen Vault und Datenbank
- Vor Migrationen
Sicherheitsmerkmale:
-------------------
- Dry-Run standardmäßig (keine Änderungen ohne --apply)
- Interaktive Bestätigung (außer mit --yes)
- Nur betroffene Collections werden geändert
Aufruf:
-------
python3 -m scripts.gc_qdrant_after_vault_scan --vault ./vault --mode all
python3 -m scripts.gc_qdrant_after_vault_scan --vault ./vault --mode all --apply
python3 -m scripts.gc_qdrant_after_vault_scan --vault ./vault --mode edges --apply --yes
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
--mode MODE edges | content | all (Default: all)
- edges: Nur Edges löschen
- content: Nur Chunks & Notes löschen
- all: Beides (zuerst edges, dann content)
--prefix TEXT Collection-Präfix (Default: ENV COLLECTION_PREFIX oder mindnet)
--apply Führt tatsächliches Löschen durch (sonst Dry-Run)
--yes Keine interaktive Bestätigung
--batch-size N Batch-Größe für Filter (Default: 1000)
Änderungen:
-----------
v2.1.0 (2025-12-15): Kompatibilität mit WP-14 Modularisierung
- Aktualisiert: Import-Pfade für neue Struktur
v1.0.0 (2025-09-05): Initial Release
"""
from __future__ import annotations
import argparse, os, glob, json, sys
from typing import Iterable, Set, Tuple, List
@@ -54,7 +77,7 @@ from qdrant_client import QdrantClient
from qdrant_client.http import models as rest
from app.core.parser import read_markdown, normalize_frontmatter, validate_required_frontmatter # :contentReference[oaicite:5]{index=5}
from app.core.qdrant import QdrantConfig, get_client, collection_names # :contentReference[oaicite:6]{index=6}
from app.core.database.qdrant import QdrantConfig, get_client, collection_names # :contentReference[oaicite:6]{index=6}
def iter_note_ids_from_vault(vault_root: str) -> Set[str]:
"""Liest alle Markdown-Dateien im Vault und sammelt valide Frontmatter-IDs."""
+58 -28
View File
@@ -1,40 +1,70 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/health_check_mindnet.py
FILE: scripts/health_check_mindnet.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Health-Check für den mindnet-Retriever-/Query-Endpoint.
Zweck:
-------
Health-Check für den mindnet /query-Retriever-Endpoint.
Prüft Verfügbarkeit, Antwortzeit und Ergebnisqualität.
Funktion:
- Führt POST-Requests auf /query in verschiedenen Modi aus (standard: semantic + hybrid).
- Prüft Status-Code, JSON-Struktur und Anzahl der Treffer.
- Kennzeichnet Probleme als:
- status="ok"
- status="warning" (z.B. Timeout)
- status="error" (harte Fehler wie HTTP-Fehler, JSON-Fehler etc.)
Funktionsweise:
---------------
1. Führt POST-Requests auf /query in verschiedenen Modi aus
2. Prüft für jeden Modus:
- HTTP-Status-Code (erwartet 200)
- JSON-Struktur (erwartet Objekt mit results-Array)
- Anzahl der Treffer (mindestens min-results)
- Antwortzeit (Latency)
3. Klassifiziert Ergebnisse:
- ok: Alles in Ordnung
- warning: Timeout oder unerwartetes Verhalten
- error: HTTP-Fehler, JSON-Fehler, zu wenige Ergebnisse
Exit-Code:
- Default (tolerant):
- overall_status = "ok" (inkl. warnings) → Exit-Code 0
- overall_status = "error" → Exit-Code 1
- Mit --strict:
- warnings werden wie errors behandelt → Exit-Code 1
Ergebnis-Interpretation:
------------------------
- Ausgabe: Menschlich lesbare Zusammenfassung + JSON-Report
- overall_status: ok | warning | error
- Exit-Code 0: ok (tolerant) oder ok/warning (strict)
- Exit-Code 1: error (tolerant) oder warning/error (strict)
Beispiele:
Verwendung:
-----------
- Monitoring und Alerting (z.B. cronjob)
- CI/CD-Pipelines (Validierung nach Deployment)
- Debugging von Performance-Problemen
- Integration in externe Monitoring-Tools (n8n, etc.)
python scripts/health_check_mindnet.py \
--url http://127.0.0.1:8001/query \
--query "embeddings" \
--top-k 3
Hinweise:
---------
- Standard: Prüft semantic und hybrid Modi
- Tolerant: Warnings führen nicht zu Exit-Code 1
- Strict: Warnings werden wie Errors behandelt
- JSON-Ausgabe für maschinelle Weiterverarbeitung
python scripts/health_check_mindnet.py \
--url http://127.0.0.1:8001/query \
--query "embeddings" \
--top-k 3 \
--timeout 15 \
--modes hybrid
Aufruf:
-------
python3 scripts/health_check_mindnet.py --url http://127.0.0.1:8001/query
python3 scripts/health_check_mindnet.py --query "test" --top-k 5 --modes semantic hybrid
python3 scripts/health_check_mindnet.py --strict
# Strenger Modus (warnings → Exit-Code 1)
python scripts/health_check_mindnet.py --strict
Parameter:
----------
--url URL Vollständige URL des /query-Endpunkts (Default: http://127.0.0.1:8001/query)
--query TEXT Test-Query (Default: embeddings)
--top-k INT Anzahl der erwarteten Ergebnisse (Default: 3)
--timeout FLOAT Timeout in Sekunden pro Request (Default: 5.0)
--modes LIST Zu prüfende Modi (Default: semantic hybrid)
--min-results INT Minimale Anzahl erwarteter Ergebnisse (Default: 1)
--strict Warnings als Fehler behandeln (Exit-Code 1 bei warnings)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.0.0: Initial Release
"""
from __future__ import annotations
+64 -6
View File
@@ -1,11 +1,69 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/import_markdown.py
CLI-Tool zum Importieren von Markdown-Dateien in Qdrant.
WP-15b: Implementiert den Two-Pass Workflow (Pre-Scan + Processing).
Sorgt dafür, dass der LocalBatchCache vor der Verarbeitung robust gefüllt wird.
Indiziert Notizen nach ID, Titel und Dateiname für maximale Link-Kompatibilität.
VERSION: 2.4.1
FILE: scripts/import_markdown.py
VERSION: 2.4.1 (2025-12-15)
STATUS: Active (Core)
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Hauptwerkzeug zum Importieren von Markdown-Dateien aus einem Vault in Qdrant.
Implementiert den Two-Pass Workflow (WP-15b) für robuste Edge-Validierung.
Funktionsweise:
---------------
1. PASS 1: Global Pre-Scan
- Scannt alle Markdown-Dateien im Vault
- Extrahiert Note-Kontext (ID, Titel, Dateiname)
- Füllt LocalBatchCache für semantische Edge-Validierung
- Indiziert nach ID, Titel und Dateiname für Link-Auflösung
2. PASS 2: Semantic Processing
- Verarbeitet Dateien in Batches (20 Dateien, max. 5 parallel)
- Nutzt gefüllten Cache für binäre Edge-Validierung
- Erzeugt Notes, Chunks und Edges in Qdrant
- Respektiert Hash-basierte Change Detection
Ergebnis-Interpretation:
------------------------
- Log-Ausgabe: Fortschritt und Statistiken
- Stats: processed, skipped, errors
- Exit-Code 0: Erfolgreich (auch wenn einzelne Dateien Fehler haben)
- Ohne --apply: Dry-Run (keine DB-Änderungen)
Verwendung:
-----------
- Regelmäßiger Import nach Vault-Änderungen
- Initial-Import eines neuen Vaults
- Re-Indexierung mit --force
Hinweise:
---------
- Two-Pass Workflow sorgt für robuste Edge-Validierung
- Change Detection verhindert unnötige Re-Indexierung
- Parallele Verarbeitung für Performance (max. 5 gleichzeitig)
- Cloud-Resilienz durch Semaphore-Limits
Aufruf:
-------
python3 -m scripts.import_markdown --vault ./vault --apply
python3 -m scripts.import_markdown --vault ./vault --prefix mindnet_dev --force --apply
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (Default: ./vault)
--prefix TEXT Collection-Präfix (Default: ENV COLLECTION_PREFIX oder mindnet)
--force Erzwingt Re-Indexierung aller Dateien (ignoriert Hashes)
--apply Führt tatsächliche DB-Schreibvorgänge durch (sonst Dry-Run)
Änderungen:
-----------
v2.4.1 (2025-12-15): WP-15b Two-Pass Workflow
- Implementiert Pre-Scan für LocalBatchCache
- Indizierung nach ID, Titel und Dateiname
- Batch-Verarbeitung mit Semaphore-Limits
v2.0.0: Initial Release
"""
import asyncio
import os
+46 -31
View File
@@ -1,45 +1,60 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
make_test_vault.py — erzeugt einen minimalen, nachvollziehbaren Test-Vault
FILE: scripts/make_test_vault.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active (Test-Tool)
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Version: 1.2 (2025-09-09)
Änderungen ggü. 1.1:
- Fügt **externe Links** (http/mailto) in `exp-two.md` hinzu, damit der Chunk-Payload-Exporter
`external_links` realistisch testen kann.
- Kleine Textanpassungen zur stabilen Chunk-Bildung (Absatzstruktur).
Zweck:
-------
Erzeugt einen minimalen, nachvollziehbaren Test-Vault für Entwicklung und Tests.
Enthält verschiedene Szenarien: leere Links, externe Links, verschiedene Note-Typen.
Zweck
- Kleiner Obsidian-ähnlicher Vault zum Durchspielen des Importers (Chunks/Edges).
- Szenarien: leere Links, spätere Anlage fehlender Noten, Chunk-Neuaufteilung, externe Links.
Funktionsweise:
---------------
1. Erstellt Verzeichnisstruktur (concepts, experiences, projects)
2. Generiert Test-Notizen mit vollständigem Frontmatter:
- concept-alpha.md (Basis-Concept)
- exp-one.md (verlinkt auf concept-alpha und missing-note)
- exp-two.md (verlinkt auf concept-alpha + externe Links)
- project-demo.md (verlinkt auf concept-alpha und exp-one)
3. Optional: Erstellt missing-note (mit --with-missing)
Struktur (Default: ./test_vault)
- 40_concepts/concept-alpha.md
- 20_experiences/exp-one.md (verlinkt auf [[concept-alpha]] und [[missing-note]])
- 20_experiences/exp-two.md (verlinkt auf [[concept-alpha]] + externe Links)
- 30_projects/project-demo.md (verlinkt auf [[concept-alpha]] und [[exp-one]])
Ergebnis-Interpretation:
------------------------
- Ausgabe: Erfolgsmeldung mit erstellten Dateien
- Exit-Code 0: Erfolgreich
- Exit-Code 1: Fehler (z.B. Verzeichnis existiert bereits ohne --force)
Voraussetzungen
- Keine. Rein Dateigenerierung.
Verwendung:
-----------
- Entwicklung und Testing
- Demo und Dokumentation
- CI/CD-Tests
Aufruf
python3 -m scripts.make_test_vault [--out ./test_vault] [--force] [--with-missing]
Hinweise:
---------
- Erstellt realistische Test-Daten mit verschiedenen Edge-Szenarien
- Enthält "Red Links" (missing-note) für Link-Auflösungs-Tests
- Externe Links für Chunk-Payload-Tests
Parameter
--out Zielverzeichnis (Standard: ./test_vault)
--force Bestehenden Ordner löschen und neu anlegen.
--with-missing Auch die 'missing-note' direkt anlegen (Standard: erst im 2. Lauf)
Aufruf:
-------
python3 -m scripts.make_test_vault --out ./test_vault
python3 -m scripts.make_test_vault --out ./test_vault --force --with-missing
Hinweise für Tests
1) Erster Import (dry-run oder --apply): Es gibt einen „leeren“ Link [[missing-note]].
2) Lege danach eine Datei für „missing-note“ an (mit gleicher ID im YAML) und importiere erneut:
-> Erwartung: Edges für ehemals leeren Link werden korrekt nachgezogen (references + backlink).
3) Ändere den Body von exp-one.md so, dass andere Chunk-Grenzen entstehen und importiere erneut:
-> Erwartung: Chunks/Edges/Note werden für betroffene Noten aktualisiert.
4) Prüfe externe Links (verify_chunk_texts.py betrifft nur Text; externe Links siehst du in chunk_payloads).
Parameter:
----------
--out PATH Zielverzeichnis (Default: ./test_vault)
--force Löscht bestehenden Ordner und legt neu an
--with-missing Erstellt auch missing-note direkt (Standard: erst im 2. Lauf)
Kompatibel mit:
- note.schema.json: 'created'/'updated' müssen strings sein. (Wichtig!)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.2 (2025-09-09): Externe Links hinzugefügt
v1.0.0: Initial Release
"""
from __future__ import annotations
+54 -13
View File
@@ -1,21 +1,62 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/ollama_tool_runner.py — Minimaler Tool-Caller für Ollama + mindnet
FILE: scripts/ollama_tool_runner.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
Führt den Tool-Call-Loop für mindnet_query / mindnet_subgraph aus.
Nutzt /tools/ollama (Schema) und deine FastAPI (/query, /graph).
ENV:
OLLAMA=http://127.0.0.1:11434
API_BASE=http://127.0.0.1:8000
MODEL=llama3.1
Nutzung:
python3 scripts/ollama_tool_runner.py "Frage an den Agenten"
Version:
0.1.0 (Erstanlage)
Stand:
2025-10-07
-------
Minimaler Tool-Caller für Ollama mit mindnet-Tools.
Führt Tool-Call-Loop für mindnet_query und mindnet_subgraph aus.
Funktionsweise:
---------------
1. Lädt Tool-Schema von /tools/ollama Endpoint
2. Sendet Query an Ollama mit Tool-Definitionen
3. Ollama entscheidet, welche Tools aufzurufen sind
4. Führt Tool-Calls aus:
- mindnet_query: Ruft /query Endpoint auf
- mindnet_subgraph: Ruft /graph Endpoint auf
5. Wiederholt bis keine weiteren Tool-Calls nötig sind
Ergebnis-Interpretation:
------------------------
- Ausgabe: Konversations-Verlauf mit Tool-Calls und Antworten
- Exit-Code 0: Erfolgreich
- Exit-Code 1: Fehler (z.B. API nicht erreichbar)
Verwendung:
-----------
- Testing von Tool-Integration
- Demo der Agent-Funktionalität
- Entwicklung neuer Tools
Hinweise:
---------
- Nutzt Ollama als LLM-Backend
- Tool-Schema wird von mindnet API bereitgestellt
- Unterstützt mehrere Tool-Calls in einer Konversation
Aufruf:
-------
python3 scripts/ollama_tool_runner.py "Frage an den Agenten"
Parameter:
----------
Keine CLI-Parameter. Query als erstes Argument.
Umgebungsvariablen:
-------------------
OLLAMA (Default: http://127.0.0.1:11434)
API_BASE (Default: http://127.0.0.1:8000)
MODEL (Default: llama3.1)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v0.1.0 (2025-10-07): Initial Release
"""
from __future__ import annotations
+56 -7
View File
@@ -1,13 +1,63 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
FILE: scripts/parse_validate_notes.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Validiert alle Markdown-Dateien in einem Vault auf strukturelle Korrektheit.
Prüft Frontmatter-Validität und Note-Payload-Erzeugung ohne Datenbank-Upsert.
Funktionsweise:
---------------
1. Scannt rekursiv alle .md-Dateien im angegebenen Vault-Verzeichnis
2. Für jede Datei:
- Liest und parst Markdown mit Frontmatter
- Validiert erforderliche Frontmatter-Felder (id, title, type)
- Erzeugt Note-Payload (validiert durch JSON-Serialisierung)
3. Gibt Statistik aus: Anzahl valider vs. invalider Dateien
Ergebnis-Interpretation:
------------------------
- Exit-Code 0: Alle Dateien sind valide
- Exit-Code 1: Mindestens eine Datei ist invalide
- Ausgabe: "✅ Valid: X | ❌ Invalid: Y"
- Fehlerdetails werden auf stderr ausgegeben
Häufige Fehler:
--------------
- Fehlende oder ungültige Frontmatter-Felder (id, title, type)
- JSON-Serialisierungsfehler im Payload (z.B. ungültige Datentypen)
- Encoding-Probleme beim Lesen der Datei
Aufruf:
-------
python3 -m scripts.parse_validate_notes --vault ./vault
python3 -m scripts.parse_validate_notes --vault ./vault --include "**/*.md" --exclude /.obsidian/ /_imported/
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
--include PATTERN Glob-Pattern für Dateien (Default: "**/*.md")
--exclude PATH Pfade zum Ausschließen (Default: /.obsidian/, /_imported/)
Änderungen:
-----------
v2.1.0 (2025-12-15): Kompatibilität mit WP-14 Modularisierung
- Entfernt: app.core.note_payload (ersetzt durch ingestion_note_payload)
- Entfernt: app.core.validate_note (Validierung in make_note_payload integriert)
- Entfernt: jsonschema.ValidationError (nicht mehr benötigt)
v1.0.0: Erster Release
"""
from __future__ import annotations
import argparse
import os
import sys
import glob
from jsonschema import ValidationError
from app.core.parser import read_markdown, validate_required_frontmatter, normalize_frontmatter
from app.core.note_payload import make_note_payload
from app.core.validate_note import validate_note_payload
from app.core.ingestion.ingestion_note_payload import make_note_payload
@@ -39,11 +89,10 @@ def main():
parsed = read_markdown(path)
fm = normalize_frontmatter(parsed.frontmatter)
validate_required_frontmatter(fm)
# Note-Payload gemäß note.schema.json validieren
payload = make_note_payload(parsed, vault_root=root)
validate_note_payload(payload)
# Note-Payload wird in make_note_payload bereits validiert (JSON-Serialisierung)
payload = make_note_payload(parsed, vault_root=root, file_path=path)
ok += 1
except (ValidationError, ValueError) as e:
except (ValueError, TypeError, KeyError, AttributeError) as e:
failed += 1
print(f"❌ {os.path.relpath(path, root)} :: {e}", file=sys.stderr)
+148 -83
View File
@@ -1,24 +1,158 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/payload_dryrun.py (zeigt, was VOR dem Upsert tatsächlich in den Payloads steht)
- KEIN Überschreiben der Note-Payload mehr
- types.yaml ist maßgeblich (gemäß app/core/note_payload.py & chunk_payload.py)
FILE: scripts/payload_dryrun.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Zeigt die Payload-Struktur, die vor dem Datenbank-Upsert erzeugt würde.
Nützlich zur Validierung der Payload-Erzeugung und Konfiguration (types.yaml).
Funktionsweise:
---------------
1. Scannt alle Markdown-Dateien im Vault
2. Für jede Datei:
- Parst Markdown mit Frontmatter
- Erzeugt Note-Payload (wie in make_note_payload)
- Erstellt Chunks via assemble_chunks
- Erzeugt Chunk-Payloads (wie in make_chunk_payloads)
- Optional: Erzeugt Edges (mit --with-edges)
3. Gibt JSON pro Note aus mit Payload-Zusammenfassung
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON-Objekte (ein Objekt pro Note, eine Zeile pro Objekt)
- Jedes Objekt enthält:
* note_id, title, type, path
* note_payload: retriever_weight, chunk_profile
* chunks_summary: count, first (erste 3 Chunks mit Metadaten)
* edges_summary (nur mit --with-edges): total, by_kind
Verwendung:
-----------
- Validierung der types.yaml Konfiguration
- Debugging von Payload-Erzeugungsproblemen
- Analyse der Chunk-Struktur vor dem Import
- Prüfung von retriever_weight und chunk_profile Zuweisungen
Hinweise:
---------
- types.yaml ist maßgeblich für Payload-Erzeugung
- Frontmatter-Überschreibungen werden berücksichtigt
- Keine Datenbank-Operationen, rein analytisch
- Chunking nutzt vollständiges assemble_chunks (nicht vereinfacht)
Aufruf:
-------
python3 -m scripts.payload_dryrun --vault ./vault
python3 -m scripts.payload_dryrun --vault ./vault --note-id my-note-id
python3 -m scripts.payload_dryrun --vault ./vault --with-edges
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
--note-id ID Nur eine bestimmte Note verarbeiten (optional)
--with-edges Edge-Erzeugung einschließen (optional)
Änderungen:
-----------
v2.1.0 (2025-12-15): Kompatibilität mit WP-14 Modularisierung
- Entfernt: Fallback für app.core.edges
- Verwendet direkt: app.core.derive_edges
- Parameter korrigiert: chunk_payloads → chunks, note_level_refs → note_level_references
v1.0.0: Erster Release
"""
from __future__ import annotations
import argparse, os, json
import argparse, os, json, asyncio
from typing import Any, Dict, List, Optional
from app.core.parser import read_markdown, normalize_frontmatter, validate_required_frontmatter
from app.core.chunking import assemble_chunks
from app.core.ingestion.ingestion_note_payload import make_note_payload
from app.core.ingestion.ingestion_chunk_payload import make_chunk_payloads
try:
from app.core.derive_edges import build_edges_for_note
except Exception:
from app.core.edges import build_edges_for_note # type: ignore
from app.core.graph.graph_derive_edges import build_edges_for_note
def main():
async def process_file(path: str, root: str, args):
"""Verarbeitet eine einzelne Datei asynchron."""
parsed = read_markdown(path)
if not parsed:
return None
fm = normalize_frontmatter(parsed.frontmatter)
try:
validate_required_frontmatter(fm)
except Exception as e:
print(json.dumps({"path": path, "error": f"invalid frontmatter: {e}"}))
return None
if args.note_id and fm.get("id") != args.note_id:
return None
# Note-Payload exakt so, wie der Importer ihn baut (types.yaml maßgeblich)
note_pl = make_note_payload(parsed,
vault_root=root,
hash_source="parsed",
hash_normalize="canonical",
file_path=path)
body_text = getattr(parsed, "body", "") or ""
chunks = await assemble_chunks(fm["id"], body_text, fm.get("type","concept"))
chunk_note = {
"frontmatter": fm,
"id": fm.get("id"),
"type": fm.get("type"),
"title": fm.get("title"),
"path": note_pl.get("path") or path,
"note_id": note_pl.get("note_id"),
"tags": fm.get("tags"),
}
# make_chunk_payloads bestimmt Werte ebenfalls aus types.yaml (Frontmatter wird ignoriert)
chunk_pls = make_chunk_payloads(
chunk_note,
note_pl["path"],
chunks,
note_text=body_text,
types_cfg=None, # Loader aus Datei; kein Override von außen
file_path=path,
)
out = {
"note_id": note_pl.get("note_id") or fm.get("id"),
"title": fm.get("title"),
"type": fm.get("type"),
"note_payload": {
"retriever_weight": note_pl.get("retriever_weight"),
"chunk_profile": note_pl.get("chunk_profile")
},
"chunks_summary": {
"count": len(chunk_pls),
"first": [
{k: chunk_pls[i].get(k) for k in ("chunk_id","index","ord","retriever_weight","chunk_profile","neighbors_prev","neighbors_next")}
for i in range(min(3, len(chunk_pls)))
]
},
"path": note_pl.get("path")
}
if args.with_edges:
edges = build_edges_for_note(
note_id=note_pl.get("note_id") or fm.get("id"),
chunks=chunk_pls,
note_level_references=note_pl.get("references") or [],
include_note_scope_refs=False,
)
kinds = {}
for e in edges:
k = (e.get("relation") or e.get("kind") or "edge")
kinds[k] = kinds.get(k, 0) + 1
out["edges_summary"] = {"total": len(edges), "by_kind": kinds}
return out
async def main_async():
ap = argparse.ArgumentParser()
ap.add_argument("--vault", required=True)
ap.add_argument("--note-id")
@@ -35,81 +169,12 @@ def main():
files.sort()
for path in files:
parsed = read_markdown(path)
if not parsed:
continue
fm = normalize_frontmatter(parsed.frontmatter)
try:
validate_required_frontmatter(fm)
except Exception as e:
print(json.dumps({"path": path, "error": f"invalid frontmatter: {e}"}))
continue
result = await process_file(path, root, args)
if result:
print(json.dumps(result, ensure_ascii=False))
if args.note_id and fm.get("id") != args.note_id:
continue
# Note-Payload exakt so, wie der Importer ihn baut (types.yaml maßgeblich)
note_pl = make_note_payload(parsed,
vault_root=root,
hash_mode="body",
hash_normalize="canonical",
hash_source="parsed",
file_path=path)
body_text = getattr(parsed, "body", "") or ""
chunks = assemble_chunks(fm["id"], body_text, fm.get("type","concept"))
chunk_note = {
"frontmatter": fm,
"id": fm.get("id"),
"type": fm.get("type"),
"title": fm.get("title"),
"path": note_pl.get("path") or path,
"note_id": note_pl.get("note_id"),
"tags": fm.get("tags"),
}
# make_chunk_payloads bestimmt Werte ebenfalls aus types.yaml (Frontmatter wird ignoriert)
chunk_pls = make_chunk_payloads(
chunk_note,
note_pl["path"],
chunks,
note_text=body_text,
types_cfg=None, # Loader aus Datei; kein Override von außen
file_path=path,
)
out = {
"note_id": note_pl.get("note_id") or fm.get("id"),
"title": fm.get("title"),
"type": fm.get("type"),
"note_payload": {
"retriever_weight": note_pl.get("retriever_weight"),
"chunk_profile": note_pl.get("chunk_profile")
},
"chunks_summary": {
"count": len(chunk_pls),
"first": [
{k: chunk_pls[i].get(k) for k in ("chunk_id","index","ord","retriever_weight","chunk_profile","neighbors_prev","neighbors_next")}
for i in range(min(3, len(chunk_pls)))
]
},
"path": note_pl.get("path")
}
if args.with_edges:
edges = build_edges_for_note(
note_id=note_pl.get("note_id") or fm.get("id"),
chunk_payloads=chunk_pls,
note_level_refs=note_pl.get("references") or [],
include_note_scope_refs=False,
)
kinds = {}
for e in edges:
k = (e.get("relation") or e.get("kind") or "edge")
kinds[k] = kinds.get(k, 0) + 1
out["edges_summary"] = {"total": len(edges), "by_kind": kinds}
print(json.dumps(out, ensure_ascii=False))
def main():
asyncio.run(main_async())
if __name__ == "__main__":
main()
+56
View File
@@ -1,4 +1,60 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
FILE: scripts/preview_chunks.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Zeigt eine Vorschau der Chunk-Struktur für Notizen im Vault.
Nützlich zur Analyse der Chunking-Strategie und Nachbarschafts-Links.
Funktionsweise:
---------------
1. Scannt alle Markdown-Dateien im Vault
2. Für jede Datei:
- Erzeugt Note-Payload
- Erstellt Chunks via assemble_chunks
- Erzeugt Chunk-Payloads
3. Gibt JSON pro Note aus mit Chunk-Details
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON-Objekte (ein Objekt pro Note, eine Zeile pro Objekt)
- Jedes Objekt enthält:
* note_id, title
* num_chunks: Anzahl der Chunks
* avg_tokens: Durchschnittliche Token pro Chunk
* chunks: Array mit Chunk-Details (id, tokens, section, prev, next)
Verwendung:
-----------
- Analyse der Chunk-Verteilung
- Validierung der Nachbarschafts-Links
- Debugging von Chunking-Problemen
Hinweise:
---------
- Nutzt synchrones assemble_chunks (kann async sein)
- Zeigt nur Struktur, keine Inhalte
Aufruf:
-------
python3 -m scripts.preview_chunks --vault ./vault
python3 -m scripts.preview_chunks --vault ./vault --note-id my-note-id
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
--note-id ID Nur eine bestimmte Note verarbeiten (optional)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.0.0: Initial Release
"""
from __future__ import annotations
import argparse, os, glob, json
from app.core.parser import read_markdown, normalize_frontmatter, validate_required_frontmatter
+84 -42
View File
@@ -1,38 +1,79 @@
# scripts/prune_qdrant_vs_vault.py
# -----------------------------------------------------------------------------
# Name: prune_qdrant_vs_vault.py
# Version: 1.0.0 (2025-09-08)
# Zweck: Entfernt verwaiste Qdrant-Einträge (notes/chunks/edges), wenn
# die zugehörigen Markdown-Dateien im Vault nicht mehr existieren.
#
# Was es macht:
# - Liest alle note_id aus dem Vault (Frontmatter: id / note_id).
# - Liest alle note_id aus Qdrant (mindnet_notes).
# - Bildet die Differenz (nur in Qdrant vorhandene, im Vault fehlende).
# - Löscht für jede verwaiste note_id:
# * Notes-Point(s)
# * Alle Chunks der Note
# * Alle Edges, die auf diese Note referenzieren
# (source_id == note_id ODER target_id == note_id ODER
# source_note_id == note_id ODER target_note_id == note_id)
#
# Hinweise:
# - Kein globaler Delete. Nur betroffene note_id.
# - Dry-Run standardmäßig; tatsächliches Löschen erst mit --apply.
# - Interaktive Bestätigung (abschaltbar mit --yes).
#
# Aufruf:
# python3 -m scripts.prune_qdrant_vs_vault --vault ./vault --prefix mindnet
# python3 -m scripts.prune_qdrant_vs_vault --vault ./vault --prefix mindnet --apply
# python3 -m scripts.prune_qdrant_vs_vault --vault ./vault --prefix mindnet --apply --yes
#
# Voraussetzungen:
# - Ausführung im aktivierten venv empfohlen: source .venv/bin/activate
# - Qdrant läuft lokal (oder URL/API-Key in ENV), siehe app/core/qdrant.py
#
# Änderungen:
# - 1.0.0: Erster Release.
# -----------------------------------------------------------------------------
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
FILE: scripts/prune_qdrant_vs_vault.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Zweck:
-------
Bereinigt verwaiste Einträge in Qdrant, wenn die zugehörigen Markdown-Dateien
im Vault nicht mehr existieren. Stellt Konsistenz zwischen Vault und Datenbank her.
Funktionsweise:
---------------
1. Liest alle note_id aus dem Vault (aus Frontmatter: id / note_id)
2. Liest alle note_id aus Qdrant (Collection: {prefix}_notes)
3. Berechnet Differenz: note_ids nur in Qdrant vorhanden (verwaist)
4. Für jede verwaiste note_id (nur mit --apply):
- Löscht Note-Point(s) aus {prefix}_notes
- Löscht alle Chunks der Note aus {prefix}_chunks
- Löscht alle Edges, die auf diese Note referenzieren:
* source_id == note_id
* target_id == note_id
* source_note_id == note_id
* target_note_id == note_id
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON mit Preview-Informationen
* mode: "DRY-RUN" oder "APPLY"
* counts: Statistiken (vault_note_ids, qdrant_note_ids, orphans)
* orphans_sample: Erste 20 verwaiste note_ids
- Bei --apply: Zusätzlich JSON mit deleted-Statistiken
* deleted.notes: Anzahl gelöschter Note-Points
* deleted.chunks: Anzahl gelöschter Chunks
* deleted.edges: Anzahl gelöschter Edges
Verwendung:
-----------
- Regelmäßige Wartung nach Vault-Bereinigung
- Vor Migrationen oder größeren Umstrukturierungen
- Konsistenz-Check zwischen Vault und Datenbank
Sicherheitsmerkmale:
-------------------
- Dry-Run standardmäßig (keine Änderungen ohne --apply)
- Interaktive Bestätigung (außer mit --yes)
- Nur betroffene note_ids werden gelöscht (kein globaler Delete)
- Zeigt Preview vor Ausführung
Aufruf:
-------
# Dry-Run (nur Analyse)
python3 -m scripts.prune_qdrant_vs_vault --vault ./vault --prefix mindnet
# Tatsächliches Löschen
python3 -m scripts.prune_qdrant_vs_vault --vault ./vault --prefix mindnet --apply
# Ohne Rückfrage
python3 -m scripts.prune_qdrant_vs_vault --vault ./vault --prefix mindnet --apply --yes
Parameter:
----------
--vault PATH Pfad zum Vault-Verzeichnis (erforderlich)
--prefix TEXT Collection-Präfix (Default: mindnet)
--apply Führt tatsächliches Löschen durch (sonst nur Dry-Run)
--yes Keine interaktive Bestätigung
Änderungen:
-----------
v2.1.0 (2025-12-15): Kompatibilität mit WP-14 Modularisierung
- Geändert: parse_markdown_file → read_markdown + normalize_frontmatter
- Parsing-Logik an neue API angepasst
v1.0.0 (2025-09-08): Erster Release
"""
import argparse
import json
@@ -44,19 +85,20 @@ from typing import Dict, List, Set, Tuple
from qdrant_client import QdrantClient
from qdrant_client.http import models as rest
from app.core.qdrant import QdrantConfig, get_client, collection_names
from app.core.parser import parse_markdown_file # nutzt euer bestehendes Parsing/Schema
from app.core.database.qdrant import QdrantConfig, get_client, collection_names
from app.core.parser import read_markdown, normalize_frontmatter
def read_vault_note_ids(vault_dir: Path) -> Set[str]:
note_ids: Set[str] = set()
for p in vault_dir.rglob("*.md"):
try:
parsed = parse_markdown_file(str(p))
fm = parsed.frontmatter if hasattr(parsed, "frontmatter") else (parsed.get("frontmatter") or {})
nid = fm.get("id") or fm.get("note_id")
if nid:
note_ids.add(str(nid))
parsed = read_markdown(str(p))
if parsed:
fm = normalize_frontmatter(parsed.frontmatter) if parsed.frontmatter else {}
nid = fm.get("id") or fm.get("note_id")
if nid:
note_ids.add(str(nid))
except Exception:
# still und leise weiter – wir wollen robust sein
continue
+50 -16
View File
@@ -1,25 +1,59 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Script: scripts/report_hashes.py — Übersicht & Lücken bei Mehrfach-Hashes
Version: 1.0.0
Datum: 2025-09-10
FILE: scripts/report_hashes.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Funktion
--------
Listet je Note die vorhandenen Einträge im Feld `hashes` (Signaturen: <mode>:<source>:<normalize>)
und meldet fehlende Soll-Keys. Eignet sich als CI-Check.
Zweck:
-------
Erstellt Übersicht über Hash-Signaturen in Note-Payloads.
Meldet fehlende Soll-Keys für Multi-Hash Change Detection.
Optionen
--------
--prefix TEXT Collection-Prefix (CLI überschreibt ENV)
--require K [K ...] Zusätzliche Soll-Keys (Default: body|frontmatter|full:parsed:canonical)
--fail-on-missing Exitcode 2, wenn fehlende Keys gefunden werden
Funktionsweise:
---------------
1. Lädt alle Notes aus {prefix}_notes
2. Prüft für jede Note das `hashes` Feld
3. Vergleicht vorhandene Keys mit Soll-Keys
4. Meldet fehlende Keys pro Note
Beispiele
Ergebnis-Interpretation:
------------------------
- Ausgabe: JSON mit Hash-Übersicht
* notes_total: Anzahl geprüfter Notizen
* notes_with_missing: Anzahl Notizen mit fehlenden Keys
* missing_keys: Liste fehlender Keys pro Note
- Exit-Code 0: Keine fehlenden Keys (oder --fail-on-missing nicht gesetzt)
- Exit-Code 2: Fehlende Keys gefunden (nur mit --fail-on-missing)
Verwendung:
-----------
- CI/CD-Validierung der Hash-Integrität
- Audit nach Migrationen
- Prüfung der Change Detection Funktionalität
Hinweise:
---------
python3 -m scripts.report_hashes --prefix mindnet
python3 -m scripts.report_hashes --require frontmatter:raw:none --fail-on-missing
- Multi-Hash Format: <mode>:<source>:<normalize>
- Standard Soll-Keys: body:parsed:canonical, full:parsed:canonical
- Kann zusätzliche Keys via --require anfordern
Aufruf:
-------
python3 -m scripts.report_hashes --prefix mindnet
python3 -m scripts.report_hashes --require frontmatter:raw:none --fail-on-missing
Parameter:
----------
--prefix TEXT Collection-Präfix (überschreibt ENV COLLECTION_PREFIX)
--require KEY ... Zusätzliche Soll-Keys (Default: body:parsed:canonical, full:parsed:canonical)
--fail-on-missing Exit-Code 2, wenn fehlende Keys gefunden werden
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.0.0 (2025-09-10): Initial Release
"""
from __future__ import annotations
@@ -29,7 +63,7 @@ import os
from typing import List, Dict, Any
from qdrant_client.http import models as rest
from app.core.qdrant import QdrantConfig, get_client
from app.core.database.qdrant import QdrantConfig, get_client
def collections(prefix: str):
return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges"
+62 -36
View File
@@ -1,49 +1,75 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Name: scripts/reset_qdrant.py
Version: v1.2.1 (2025-12-11)
Kurzbeschreibung:
Sicheres Zurücksetzen der Qdrant-Collections für EIN Projektpräfix. Das Skript
ermittelt zunächst die tatsächlich betroffenen Collections und zeigt eine
Übersicht an. Anschließend wird der User um Bestätigung gebeten (interaktive
Abfrage), bevor eine der Aktionen ausgeführt wird:
FILE: scripts/reset_qdrant.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active (Core)
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
- wipe: Löscht die Collections komplett und legt sie gemäß Projekt-Defaults neu an.
**Neu**: Danach werden *immer* die Payload-Indizes & Schema-Ergänzungen
über ensure_payload_indexes() idempotent eingerichtet (falls nicht mit --no-indexes deaktiviert).
- truncate: Löscht nur alle Points (Inhalte), behält die Collection-Settings.
**Neu**: Optional (Default) werden im Anschluss die Payload-Indizes geprüft/ergänzt.
Zweck:
-------
Sicheres Zurücksetzen der Qdrant-Collections für ein Projektpräfix.
Ermöglicht vollständigen Neustart (wipe) oder Löschen nur der Inhalte (truncate).
Aufruf (aus Projekt-Root, im venv):
python3 -m scripts.reset_qdrant --mode wipe [--prefix PREFIX] [--yes] [--dry-run]
python3 -m scripts.reset_qdrant --mode truncate [--prefix PREFIX] [--yes] [--dry-run]
Funktionsweise:
---------------
1. Ermittelt betroffene Collections (notes, chunks, edges für Präfix)
2. Zeigt Preview der existierenden Collections
3. Interaktive Bestätigung (außer mit --yes)
4. Führt Aktion aus:
- wipe: Löscht Collections komplett, legt neu an, richtet Indizes ein
- truncate: Löscht nur Points, behält Collection-Settings, prüft Indizes
5. Richtet Payload-Indizes idempotent ein (außer mit --no-indexes)
Parameter:
--mode wipe | truncate (Pflicht)
--prefix Collection-Prefix (Default: env COLLECTION_PREFIX oder 'mindnet')
--yes Keine Rückfrage, direkt ausführen (CI/CD geeignet)
--dry-run Nur anzeigen, was passieren würde; nichts ändern
--no-indexes Überspringt den Schritt ensure_payload_indexes() (Standard: Indizes/Schema werden geprüft/ergänzt)
Ergebnis-Interpretation:
------------------------
- Preview: Zeigt betroffene Collections vor Ausführung
- Exit-Code 0: Erfolgreich
- Exit-Code 1: Abgebrochen oder keine Aktion
- Exit-Code 2: Verbindungs- oder Konfigurationsfehler
Umgebungsvariablen (optional):
QDRANT_URL, QDRANT_API_KEY, COLLECTION_PREFIX, VECTOR_DIM (Default 384)
(Zusätzliche ENV für Named Vectors etc. werden innerhalb ensure_collections/ensure_payload_indexes berücksichtigt.)
Verwendung:
-----------
- Vor größeren Migrationen oder Schema-Änderungen
- Bei Inkonsistenzen in der Datenbank
- Für Entwicklung/Testing (schneller Reset)
- CI/CD-Pipelines (mit --yes)
Sicherheitsmerkmale:
- Betrachtet ausschließlich Collections des angegebenen Präfixes.
- Listet vor Ausführung die tatsächlich existierenden Ziel-Collections auf.
- Fragt interaktiv nach Bestätigung (es sei denn --yes ist gesetzt).
-------------------
- Betrachtet nur Collections des angegebenen Präfixes
- Listet betroffene Collections vor Ausführung auf
- Interaktive Bestätigung (außer mit --yes)
- Dry-Run Modus verfügbar
Exitcodes:
0 = OK, 1 = abgebrochen/keine Aktion, 2 = Verbindungs-/Konfigurationsfehler
Aufruf:
-------
python3 -m scripts.reset_qdrant --mode wipe --prefix mindnet
python3 -m scripts.reset_qdrant --mode truncate --prefix mindnet --yes
python3 -m scripts.reset_qdrant --mode wipe --dry-run
Changelog:
v1.2.1: Fix: load_dotenv() hinzugefügt, damit VECTOR_DIM aus .env gelesen wird.
v1.2.0: ensure_payload_indexes() nach wipe/truncate standardmäßig ausführen (idempotent); --no-indexes Flag ergänzt.
v1.1.1: Stabilisierung & Preview (2025-09-05).
v1.1.0: Interaktive Bestätigung, --yes/--dry-run hinzugefügt, Preview der betroffenen Collections.
v1.0.0: Wipe/Truncate ohne Bestätigungsabfrage.
Parameter:
----------
--mode MODE wipe | truncate (Pflicht)
- wipe: Collections löschen & neu anlegen
- truncate: Nur Points löschen, Settings behalten
--prefix TEXT Collection-Präfix (Default: ENV COLLECTION_PREFIX oder mindnet)
--yes Keine Rückfrage, direkt ausführen (CI/CD)
--dry-run Nur anzeigen, was passieren würde
--no-indexes Überspringt ensure_payload_indexes() (Standard: Indizes werden geprüft/ergänzt)
Umgebungsvariablen:
-------------------
QDRANT_URL, QDRANT_API_KEY, COLLECTION_PREFIX, VECTOR_DIM (Default: 768)
Änderungen:
-----------
v2.1.0 (2025-12-15): Kompatibilität mit WP-14 Modularisierung
- Aktualisiert: Import-Pfade für neue Struktur
v1.2.1 (2025-12-11): Fix load_dotenv() für VECTOR_DIM
v1.2.0: ensure_payload_indexes() standardmäßig nach wipe/truncate
v1.1.0: Interaktive Bestätigung, --yes/--dry-run
v1.0.0: Initial Release
"""
from __future__ import annotations
import argparse
@@ -57,7 +83,7 @@ from dotenv import load_dotenv
from qdrant_client import QdrantClient
from qdrant_client.http import models as rest
from app.core.qdrant import (
from app.core.database.qdrant import (
QdrantConfig,
get_client,
ensure_collections,
+60 -14
View File
@@ -1,20 +1,66 @@
#!/usr/bin/env python3
# scripts/resolve_unresolved_references.py
# -*- coding: utf-8 -*-
"""
resolve_unresolved_references.py — Unaufgelöste Wikilinks in Qdrant nachträglich auflösen
FILE: scripts/resolve_unresolved_references.py
VERSION: 2.1.0 (2025-12-15)
STATUS: Active
COMPATIBILITY: v2.9.1 (Post-WP14/WP-15b)
Version: 1.1.0 (Fixed for v2.6 Architecture)
Zweck:
-------
Löst unaufgelöste Wikilinks in Qdrant nachträglich auf.
Findet Edges mit status=="unresolved" und versucht sie über Titel/Alias aufzulösen.
Zweck
------
- Findet Edges in {prefix}_edges mit payload.status=="unresolved".
- Baut einen In-Memory Index aller Notizen (Titel/Alias -> ID).
- Aktualisiert die Edges (setzt target_id, entfernt status).
- Erzeugt symmetrische 'backlink'-Kanten für 'references'.
Funktionsweise:
---------------
1. Baut Lookup-Index aus allen Notizen:
- Mapping: lower(title) -> note_id
- Mapping: lower(alias) -> note_id
2. Findet alle Edges mit status=="unresolved"
3. Versucht Auflösung über Lookup-Index
4. Aktualisiert erfolgreich aufgelöste Edges:
- Setzt target_id
- Entfernt status
- Fügt resolution="healed_by_script" hinzu
5. Erzeugt Backlinks für erfolgreich aufgelöste references-Edges
Aufruf
------
python3 -m scripts.resolve_unresolved_references --apply
Ergebnis-Interpretation:
------------------------
- Log-Ausgabe: Fortschritt und Statistiken
- "Resolvable: X/Y": Anzahl aufgelösbarer Edges
- Ohne --apply: Dry-Run (keine DB-Änderungen)
- Exit-Code 0: Erfolgreich
Verwendung:
-----------
- Nach Import von neuen Notizen, die bestehende Links auflösen
- Reparatur von "Red Links" (Links auf noch nicht existierende Notizen)
- Wartung des Graphen nach größeren Änderungen
Hinweise:
---------
- Sucht nach status=="unresolved" in Edge-Payloads
- Auflösung erfolgt über Titel und Aliases (case-insensitive)
- Erzeugt automatisch Backlinks für references-Edges
- Batch-Verarbeitung für Performance
Aufruf:
-------
python3 -m scripts.resolve_unresolved_references --apply
python3 -m scripts.resolve_unresolved_references --prefix mindnet --limit 1000 --apply
Parameter:
----------
--prefix TEXT Collection-Präfix (Default: ENV COLLECTION_PREFIX)
--apply Führt tatsächliche DB-Änderungen durch (sonst Dry-Run)
--limit INT Maximale Anzahl zu verarbeitender Edges (0=alle, Default: 0)
--batch INT Batch-Größe für Upserts (Default: 100)
Änderungen:
-----------
v2.1.0 (2025-12-15): Dokumentation aktualisiert
v1.1.0: Fixed for v2.6 Architecture
v1.0.0: Initial Release
"""
import argparse
@@ -24,8 +70,8 @@ import uuid
from typing import List, Dict, Any, Iterable
from qdrant_client import models
from app.core.qdrant import QdrantConfig, get_client
from app.core.qdrant_points import points_for_edges
from app.core.database.qdrant import QdrantConfig, get_client
from app.core.database.qdrant_points import points_for_edges
# Logging Setup
logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")
Loaded 100 of 128 files, more files were not shown because too many files have changed in this diff. Show more