Compare commits

..
Author SHA1 Message Date
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
55 changed files with 4279 additions and 1291 deletions

No files matched your search

+46 -24
View File
@@ -1,6 +1,8 @@
""" """
FILE: app/core/chunking/chunking_parser.py 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 import re
from typing import List, Tuple, Set 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„(])') _SENT_SPLIT = re.compile(r'(?<=[.!?])\s+(?=[A-ZÄÖÜ0-9„(])')
def split_sentences(text: str) -> list[str]: 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()) text = _WS.sub(' ', text.strip())
if not text: return [] 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()] return [p.strip() for p in _SENT_SPLIT.split(text) if p.strip()]
def parse_blocks(md_text: str) -> Tuple[List[RawBlock], str]: 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 = [] 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) 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) 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') lines = text_without_fm.split('\n')
buffer = [] buffer = []
for line in lines: for line in lines:
stripped = line.strip() stripped = line.strip()
# H1 ignorieren (ist Doc Title) # Heading-Erkennung (H1 bis H6)
if stripped.startswith('# '): heading_match = re.match(r'^(#{1,6})\s+(.*)', stripped)
continue
# Generische Heading-Erkennung (H2 bis H6) für flexible Split-Levels
heading_match = re.match(r'^(#{2,6})\s+(.*)', stripped)
if heading_match: if heading_match:
# Buffer leeren (vorherigen Text abschließen) # Vorherigen Text-Block abschließen
if buffer: if buffer:
content = "\n".join(buffer).strip() 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 = [] buffer = []
level = len(heading_match.group(1)) level = len(heading_match.group(1))
title = heading_match.group(2).strip() title = heading_match.group(2).strip()
# Pfad-Logik: H2 setzt den Haupt-Pfad # Pfad- und Titel-Update für die Metadaten der folgenden Blöcke
if level == 2: if level == 1:
current_h2 = title current_section_title = title; section_path = "/"
section_path = f"/{current_h2}" elif level == 2:
# Bei H3+ bleibt der section_path beim Parent, aber das Level wird korrekt gesetzt current_section_title = title; section_path = f"/{current_section_title}"
blocks.append(RawBlock("heading", stripped, level, section_path, current_h2)) # Die Überschrift selbst als regulären Block hinzufügen
blocks.append(RawBlock("heading", stripped, level, section_path, current_section_title))
continue
elif not stripped: # Trenner (---) oder Leerzeilen beenden Blöcke, außer innerhalb von Callouts
if (not stripped or stripped == "---") and not line.startswith('>'):
if buffer: if buffer:
content = "\n".join(buffer).strip() 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 = [] buffer = []
if stripped == "---":
blocks.append(RawBlock("separator", "---", None, section_path, current_section_title))
else: else:
buffer.append(line) buffer.append(line)
if buffer: if buffer:
content = "\n".join(buffer).strip() 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 return blocks, h1_title
def parse_edges_robust(text: str) -> Set[str]: def parse_edges_robust(text: str) -> Set[str]:
"""Extrahiert Kanten-Kandidaten (Wikilinks, Callouts).""" """Extrahiert Kanten-Kandidaten aus Wikilinks und Callouts."""
found_edges = set() found_edges = set()
# 1. Wikilinks [[rel:kind|target]]
inlines = re.findall(r'\[\[rel:([^\|\]]+)\|?([^\]]*)\]\]', text) inlines = re.findall(r'\[\[rel:([^\|\]]+)\|?([^\]]*)\]\]', text)
for kind, target in inlines: for kind, target in inlines:
k = kind.strip().lower() k = kind.strip().lower()
t = target.strip() t = target.strip()
if k and t: found_edges.add(f"{k}:{t}") if k and t: found_edges.add(f"{k}:{t}")
# 2. Callout Edges > [!edge] kind
lines = text.split('\n') lines = text.split('\n')
current_edge_type = None current_edge_type = None
for line in lines: 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) callout_match = re.match(r'>\s*\[!edge\]\s*([^:\s]+)', stripped)
if callout_match: if callout_match:
current_edge_type = callout_match.group(1).strip().lower() current_edge_type = callout_match.group(1).strip().lower()
# Links in der gleichen Zeile des Callouts
links = re.findall(r'\[\[([^\]]+)\]\]', stripped) links = re.findall(r'\[\[([^\]]+)\]\]', stripped)
for l in links: for l in links:
if "rel:" not in l: found_edges.add(f"{current_edge_type}:{l}") if "rel:" not in l: found_edges.add(f"{current_edge_type}:{l}")
continue continue
# Links in Folgezeilen des Callouts
if current_edge_type and stripped.startswith('>'): if current_edge_type and stripped.startswith('>'):
links = re.findall(r'\[\[([^\]]+)\]\]', stripped) links = re.findall(r'\[\[([^\]]+)\]\]', stripped)
for l in links: for l in links:
if "rel:" not in l: found_edges.add(f"{current_edge_type}:{l}") 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 return found_edges
+13 -7
View File
@@ -1,7 +1,8 @@
""" """
FILE: app/core/chunking/chunking_processor.py FILE: app/core/chunking/chunking_processor.py
DESCRIPTION: Der zentrale Orchestrator für das Chunking-System. 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). - Integriert physikalische Kanten-Injektion (Propagierung).
- Stellt H1-Kontext-Fenster sicher. - Stellt H1-Kontext-Fenster sicher.
- Baut den Candidate-Pool für die WP-15b Ingestion auf. - 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) fm, body_text = extract_frontmatter_from_text(md_text)
blocks, doc_title = parse_blocks(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 "" h1_prefix = f"# {doc_title}" if doc_title else ""
# 2. Anwendung der Splitting-Strategie # 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": 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: else:
# sliding_window nutzt nun den context_prefix für das Window-Feld. chunks = await asyncio.to_thread(
chunks = await asyncio.to_thread(strategy_sliding_window, blocks, config, note_id, context_prefix=h1_prefix) strategy_sliding_window, blocks, config, note_id, context_prefix=h1_prefix
)
if not chunks: if not chunks:
return [] 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. # Zuerst die explizit im Text vorhandenen Kanten sammeln.
for ch in chunks: for ch in chunks:
# Wir extrahieren aus dem bereits (durch Propagation) angereicherten Text. # 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): for e_str in parse_edges_robust(ch.text):
parts = e_str.split(':', 1) parts = e_str.split(':', 1)
if len(parts) == 2: 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) parts = e_str.split(':', 1)
if len(parts) == 2: if len(parts) == 2:
k, t = parts 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: for ch in chunks:
ch.candidate_pool.append({"kind": k, "to": t, "provenance": "global_pool"}) 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() seen = set()
unique = [] unique = []
for c in ch.candidate_pool: for c in ch.candidate_pool:
# Eindeutigkeit über Typ, Ziel und Herkunft (Provenance)
key = (c["kind"], c["to"], c["provenance"]) key = (c["kind"], c["to"], c["provenance"])
if key not in seen: if key not in seen:
seen.add(key) seen.add(key)
+17 -11
View File
@@ -1,9 +1,8 @@
""" """
FILE: app/core/chunking/chunking_propagation.py FILE: app/core/chunking/chunking_propagation.py
DESCRIPTION: Injiziert Sektions-Kanten physisch in den Text (Embedding-Enrichment). DESCRIPTION: Injiziert Sektions-Kanten physisch in den Text (Embedding-Enrichment).
Stellt die "Gold-Standard"-Qualität von v3.1.0 wieder her. Fix v3.3.6: Nutzt robustes Parsing zur Erkennung vorhandener Kanten,
VERSION: 3.3.1 um Dopplungen direkt hinter [!edge] Callouts format-agnostisch zu verhindern.
STATUS: Active
""" """
from typing import List, Dict, Set from typing import List, Dict, Set
from .chunking_models import Chunk 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]: def propagate_section_edges(chunks: List[Chunk]) -> List[Chunk]:
""" """
Sammelt Kanten pro Sektion und schreibt sie hart in den Text und das Window. 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 # 1. Sammeln: Alle expliziten Kanten pro Sektions-Pfad aggregieren
section_map: Dict[str, Set[str]] = {} # path -> set(kind:target) 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: if not edges_to_add:
continue 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 = [] 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) kind, target = e_str.split(':', 1)
# Nur injizieren, wenn die Kante nicht bereits im Text steht injections.append(f"[[rel:{kind}|{target}]]")
token = f"[[rel:{kind}|{target}]]"
if token not in ch.text:
injections.append(token)
if injections: if injections:
# Physische Anreicherung (Der v3.1.0 Qualitäts-Fix) # Physische Anreicherung
# Triple-Newline für saubere Trennung im Embedding-Fenster # Triple-Newline für saubere Trennung im Embedding-Fenster
block = "\n\n\n" + " ".join(injections) block = "\n\n\n" + " ".join(injections)
ch.text += block ch.text += block
# ENTSCHEIDEND: Auch ins Window schreiben, da Qdrant hier sucht! # Auch ins Window schreiben, da Qdrant hier sucht!
if ch.window: if ch.window:
ch.window += block ch.window += block
else: else:
+134 -110
View File
@@ -1,142 +1,166 @@
""" """
FILE: app/core/chunking/chunking_strategies.py FILE: app/core/chunking/chunking_strategies.py
DESCRIPTION: Mathematische Splitting-Strategien. DESCRIPTION: Strategien für atomares Sektions-Chunking v3.9.9.
AUDIT v3.3.2: 100% Konformität zur 'by_heading' Spezifikation. Implementiert das 'Pack-and-Carry-Over' Verfahren nach Regel 1-3.
- Implementiert Hybrid-Safety-Net (Sliding Window für Übergrößen). - Keine redundante Kanten-Injektion.
- Breadcrumb-Kontext im Window (H1 > H2). - Strikte Einhaltung von Sektionsgrenzen via Look-Ahead.
- Sliding Window mit H1-Kontext (Gold-Standard v3.1.0). - Fix: Synchronisierung der Parameter mit dem Orchestrator (context_prefix).
""" """
from typing import List, Dict, Any, Optional from typing import List, Dict, Any, Optional
from .chunking_models import RawBlock, Chunk from .chunking_models import RawBlock, Chunk
from .chunking_utils import estimate_tokens from .chunking_utils import estimate_tokens
from .chunking_parser import split_sentences 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.""" """Baut den Breadcrumb-Kontext für das Embedding-Fenster."""
parts = [] parts = [context_prefix] if context_prefix else []
if doc_title: parts.append(doc_title) # Verhindert Dopplung, falls der Context-Prefix (H1) bereits den Sektionsnamen enthält
if sec_title and sec_title != doc_title: parts.append(sec_title) if sec_title and f"# {sec_title}" != context_prefix and sec_title not in (context_prefix or ""):
parts.append(sec_title)
prefix = " > ".join(parts) prefix = " > ".join(parts)
return f"{prefix}\n{text}".strip() if prefix else text return f"{prefix}\n{text}".strip() if prefix else text
def strategy_sliding_window(blocks: List[RawBlock], def strategy_by_heading(blocks: List[RawBlock], config: Dict[str, Any], note_id: str, context_prefix: str = "") -> List[Chunk]:
config: Dict[str, Any],
note_id: str,
context_prefix: str = "") -> List[Chunk]:
""" """
Fasst Blöcke zusammen und schneidet bei 'target' Tokens. Universelle Heading-Strategie mit Carry-Over Logik.
Ignoriert H2-Überschriften beim Splitting, um Kontext zu wahren. Synchronisiert auf context_prefix für Kompatibilität mit dem Orchestrator.
"""
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.
""" """
smart_edge = config.get("enable_smart_edge_allocation", True)
strict = config.get("strict_heading_split", False) strict = config.get("strict_heading_split", False)
target = config.get("target", 400) target = config.get("target", 400)
max_tokens = config.get("max", 600) max_tokens = config.get("max", 600)
split_level = config.get("split_level", 2) 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] = [] 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) idx = len(chunks)
win = _create_context_win(doc_title, title, txt) win = _create_win(context_prefix, title, txt)
chunks.append(Chunk( chunks.append(Chunk(
id=f"{note_id}#c{idx:02d}", note_id=note_id, index=idx, id=f"{note_id}#c{idx:02d}", note_id=note_id, index=idx,
text=txt, window=win, token_count=estimate_tokens(txt), text=txt, window=win, token_count=estimate_tokens(txt),
section_title=title, section_path=path, section_title=title, section_path=path, neighbors_prev=None, neighbors_next=None
neighbors_prev=None, neighbors_next=None
)) ))
def _flush(title, path): # --- SCHRITT 1: Gruppierung in atomare Sektions-Einheiten ---
nonlocal buf, cur_tokens sections: List[Dict[str, Any]] = []
if not buf: return curr_blocks = []
full_text = "\n\n".join(buf) for b in blocks:
if estimate_tokens(full_text) <= max_tokens: if b.kind == "heading" and b.level <= split_level:
_add_to_chunks(full_text, title, path) 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: else:
sents = split_sentences(full_text); cur_sents = []; sub_len = 0 curr_blocks.append(b)
for s in sents: if curr_blocks:
slen = estimate_tokens(s) sections.append({
if sub_len + slen > target and cur_sents: "text": "\n\n".join([x.text for x in curr_blocks]),
_add_to_chunks(" ".join(cur_sents), title, path) "meta": curr_blocks[0],
ov_s = []; ov_l = 0 "is_empty": len(curr_blocks) == 1 and curr_blocks[0].kind == "heading"
for os in reversed(cur_sents): })
if ov_l + estimate_tokens(os) < overlap:
ov_s.insert(0, os); ov_l += estimate_tokens(os) # --- SCHRITT 2: Verarbeitung der Queue ---
else: break queue = list(sections)
cur_sents = list(ov_s); cur_sents.append(s); sub_len = ov_l + slen current_chunk_text = ""
else: cur_sents.append(s); sub_len += slen current_meta = {"title": None, "path": "/"}
if cur_sents: _add_to_chunks(" ".join(cur_sents), title, path)
buf = []; cur_tokens = 0 # 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
# 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: for b in blocks:
if b.kind == "heading": b_tokens = estimate_tokens(b.text)
if b.level < split_level: _flush(b.section_title, b.section_path) curr_tokens = sum(estimate_tokens(x.text) for x in buf) if buf else 0
elif b.level == split_level: if curr_tokens + b_tokens > max_tokens and buf:
if strict or cur_tokens >= target: _flush(b.section_title, b.section_path) txt = "\n\n".join([x.text for x in buf]); idx = len(chunks)
continue win = _create_win(context_prefix, buf[0].section_title, txt)
bt = estimate_tokens(b.text) 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))
if cur_tokens + bt > max_tokens and buf: _flush(b.section_title, b.section_path) buf = []
buf.append(b.text); cur_tokens += bt buf.append(b)
if buf: if buf:
last_b = blocks[-1] if blocks else None txt = "\n\n".join([x.text for x in buf]); idx = len(chunks)
_flush(last_b.section_title if last_b else None, last_b.section_path if last_b else "/") 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 return chunks
+4 -2
View File
@@ -3,7 +3,7 @@ FILE: app/core/database/qdrant.py
DESCRIPTION: Qdrant-Client Factory und Schema-Management. DESCRIPTION: Qdrant-Client Factory und Schema-Management.
Erstellt Collections und Payload-Indizes. Erstellt Collections und Payload-Indizes.
MODULARISIERUNG: Verschoben in das database-Paket für WP-14. 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 STATUS: Active
DEPENDENCIES: qdrant_client, dataclasses, os 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. Stellt sicher, dass alle benötigten Payload-Indizes für die Suche existieren.
- notes: note_id, type, title, updated, tags - notes: note_id, type, title, updated, tags
- chunks: note_id, chunk_id, index, type, 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) notes, chunks, edges = collection_names(prefix)
@@ -156,6 +156,8 @@ def ensure_payload_indexes(client: QdrantClient, prefix: str) -> None:
("source_id", rest.PayloadSchemaType.KEYWORD), ("source_id", rest.PayloadSchemaType.KEYWORD),
("target_id", rest.PayloadSchemaType.KEYWORD), ("target_id", rest.PayloadSchemaType.KEYWORD),
("chunk_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) _ensure_index(client, edges, field, schema)
+11 -2
View File
@@ -1,10 +1,10 @@
""" """
FILE: app/core/database/qdrant_points.py 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. 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 STATUS: Active
DEPENDENCIES: qdrant_client, uuid, os DEPENDENCIES: qdrant_client, uuid, os
LAST_ANALYSIS: 2025-12-15 LAST_ANALYSIS: 2025-12-29
""" """
from __future__ import annotations from __future__ import annotations
import os import os
@@ -46,16 +46,25 @@ def points_for_chunks(prefix: str, chunk_payloads: List[dict], vectors: List[Lis
return chunks_col, points return chunks_col, points
def _normalize_edge_payload(pl: dict) -> dict: 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" 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" 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" 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") 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("kind", kind)
pl.setdefault("source_id", source_id) pl.setdefault("source_id", source_id)
pl.setdefault("target_id", target_id) pl.setdefault("target_id", target_id)
if seq is not None and "seq" not in pl: if seq is not None and "seq" not in pl:
pl["seq"] = seq pl["seq"] = seq
if target_section is not None:
pl["target_section"] = target_section
return pl return pl
def points_for_edges(prefix: str, edge_payloads: List[dict]) -> Tuple[str, List[rest.PointStruct]]: def points_for_edges(prefix: str, edge_payloads: List[dict]) -> Tuple[str, List[rest.PointStruct]]:
+11 -3
View File
@@ -1,13 +1,15 @@
""" """
FILE: app/core/graph/graph_db_adapter.py FILE: app/core/graph/graph_db_adapter.py
DESCRIPTION: Datenbeschaffung aus Qdrant für den Graphen. 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 typing import List, Dict, Optional
from qdrant_client import QdrantClient from qdrant_client import QdrantClient
from qdrant_client.http import models as rest 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 from app.core.database import collection_names
def fetch_edges_from_qdrant( def fetch_edges_from_qdrant(
@@ -19,14 +21,16 @@ def fetch_edges_from_qdrant(
) -> List[Dict]: ) -> List[Dict]:
""" """
Holt Edges aus der Datenbank basierend auf Seed-IDs. 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: if not seeds or limit <= 0:
return [] return []
# Konsistente Namensauflösung via database-Paket # Konsistente Namensauflösung via database-Paket
# Rückgabe: (notes_col, chunks_col, edges_col)
_, _, edges_col = collection_names(prefix) _, _, edges_col = collection_names(prefix)
# Wir suchen Kanten, bei denen die Seed-IDs entweder Quelle, Ziel oder Kontext-Note sind.
seed_conditions = [] seed_conditions = []
for field in ("source_id", "target_id", "note_id"): for field in ("source_id", "target_id", "note_id"):
for s in seeds: 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 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 type_filter = None
if edge_types: if edge_types:
type_conds = [ type_conds = [
@@ -52,6 +57,7 @@ def fetch_edges_from_qdrant(
flt = rest.Filter(must=must) if must else None flt = rest.Filter(must=must) if must else None
# Abfrage via Qdrant Scroll API # Abfrage via Qdrant Scroll API
# WICHTIG: with_payload=True lädt alle Metadaten (target_section, provenance etc.)
pts, _ = client.scroll( pts, _ = client.scroll(
collection_name=edges_col, collection_name=edges_col,
scroll_filter=flt, scroll_filter=flt,
@@ -60,4 +66,6 @@ def fetch_edges_from_qdrant(
with_vectors=False, 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] return [dict(p.payload) for p in pts if p.payload]
+95 -38
View File
@@ -1,10 +1,14 @@
""" """
FILE: app/core/graph/graph_derive_edges.py FILE: app/core/graph/graph_derive_edges.py
DESCRIPTION: Hauptlogik zur Kanten-Aggregation und De-Duplizierung. 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 typing import List, Optional, Dict, Tuple
from .graph_utils import ( 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 PROVENANCE_PRIORITY, load_types_registry, get_edge_defaults_for
) )
from .graph_extractors import ( from .graph_extractors import (
@@ -17,31 +21,45 @@ def build_edges_for_note(
note_level_references: Optional[List[str]] = None, note_level_references: Optional[List[str]] = None,
include_note_scope_refs: bool = False, include_note_scope_refs: bool = False,
) -> List[dict]: ) -> 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] = [] edges: List[dict] = []
# note_type für die Ermittlung der edge_defaults (types.yaml)
note_type = _get(chunks[0], "type") if chunks else "concept" 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): for idx, ch in enumerate(chunks):
cid = _get(ch, "chunk_id", "id") cid = _get(ch, "chunk_id", "id")
if not cid: continue if not cid: continue
# Verbindung Chunk -> Note
edges.append(_edge("belongs_to", "chunk", cid, note_id, note_id, { 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"), "chunk_id": cid,
"provenance": "structure", "rule_id": "structure:belongs_to", "confidence": PROVENANCE_PRIORITY["structure:belongs_to"] "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: if idx < len(chunks) - 1:
next_id = _get(chunks[idx+1], "chunk_id", "id") next_id = _get(chunks[idx+1], "chunk_id", "id")
if next_id: if next_id:
edges.append(_edge("next", "chunk", cid, next_id, note_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"] "provenance": "structure", "rule_id": "structure:order", "confidence": PROVENANCE_PRIORITY["structure:order"]
})) }))
edges.append(_edge("prev", "chunk", next_id, cid, note_id, { 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"] "provenance": "structure", "rule_id": "structure:order", "confidence": PROVENANCE_PRIORITY["structure:order"]
})) }))
# 2) Inhaltliche Kanten # 2) Inhaltliche Kanten (Explicit & Candidate Pool)
reg = load_types_registry() reg = load_types_registry()
defaults = get_edge_defaults_for(note_type, reg) defaults = get_edge_defaults_for(note_type, reg)
refs_all: List[str] = [] refs_all: List[str] = []
@@ -51,62 +69,101 @@ def build_edges_for_note(
if not cid: continue if not cid: continue
raw = _get(ch, "window") or _get(ch, "text") or "" 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) typed, rem = extract_typed_relations(raw)
for k, t in typed: for k, raw_t in typed:
edges.append(_edge(k, "chunk", cid, t, note_id, { t, sec = parse_link_target(raw_t, note_id)
"chunk_id": cid, "edge_id": _mk_edge_id(k, cid, t, "chunk", "inline:rel"), if not t: continue
"provenance": "explicit", "rule_id": "inline:rel", "confidence": PROVENANCE_PRIORITY["inline:rel"]
}))
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 [] pool = ch.get("candidate_pool") or ch.get("candidate_edges") or []
for cand in pool: 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: if t:
edges.append(_edge(k, "chunk", cid, t, note_id, { payload = {
"chunk_id": cid, "edge_id": _mk_edge_id(k, cid, t, "chunk", f"candidate:{p}"), "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) "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) call_pairs, rem2 = extract_callout_relations(rem)
for k, t in call_pairs: for k, raw_t in call_pairs:
edges.append(_edge(k, "chunk", cid, t, note_id, { t, sec = parse_link_target(raw_t, note_id)
"chunk_id": cid, "edge_id": _mk_edge_id(k, cid, t, "chunk", "callout:edge"), if not t: continue
"provenance": "explicit", "rule_id": "callout:edge", "confidence": PROVENANCE_PRIORITY["callout:edge"]
}))
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) refs = extract_wikilinks(rem2)
for r in refs: for raw_r in refs:
edges.append(_edge("references", "chunk", cid, r, note_id, { r, sec = parse_link_target(raw_r, note_id)
"chunk_id": cid, "ref_text": r, "edge_id": _mk_edge_id("references", cid, r, "chunk", "explicit:wikilink"), 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"] "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: for rel in defaults:
if rel != "references": if rel != "references":
edges.append(_edge(rel, "chunk", cid, r, note_id, { def_payload = {
"chunk_id": cid, "edge_id": _mk_edge_id(rel, cid, r, "chunk", f"edge_defaults:{rel}"), "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"] "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))
# 3) Note-Scope & De-Duplizierung refs_all.extend([parse_link_target(r, note_id)[0] for r in refs])
# 3) Note-Scope (Grobe Struktur-Verbindungen)
if include_note_scope_refs: 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: for r in refs_note:
if not r: continue
edges.append(_edge("references", "note", note_id, r, note_id, { edges.append(_edge("references", "note", note_id, r, note_id, {
"edge_id": _mk_edge_id("references", note_id, r, "note", "explicit:note_scope"), "edge_id": _mk_edge_id("references", note_id, r, "note", "explicit:note_scope"),
"provenance": "explicit", "confidence": PROVENANCE_PRIORITY["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, { edges.append(_edge("backlink", "note", r, note_id, note_id, {
"edge_id": _mk_edge_id("backlink", r, note_id, "note", "derived:backlink"), "edge_id": _mk_edge_id("backlink", r, note_id, "note", "derived:backlink"),
"provenance": "rule", "confidence": PROVENANCE_PRIORITY["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: for e in edges:
key = (str(e.get("source_id")), str(e.get("target_id")), str(e.get("kind"))) eid = e["edge_id"]
if key not in unique_map or e.get("confidence", 0) > unique_map[key].get("confidence", 0): # Höhere Confidence gewinnt bei identischer ID
unique_map[key] = e 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()) return list(unique_map.values())
+93 -21
View File
@@ -1,25 +1,36 @@
""" """
FILE: app/core/graph/graph_extractors.py FILE: app/core/graph/graph_extractors.py
DESCRIPTION: Regex-basierte Extraktion von Relationen aus Text. 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 import re
from typing import List, Tuple 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_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_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) _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) _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) _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]: def extract_typed_relations(text: str) -> Tuple[List[Tuple[str, str]], str]:
"""Extrahiert [[rel:KIND|Target]].""" """
Findet Inline-Relationen wie [[rel:depends_on Target]].
Gibt (Liste[(kind, target)], bereinigter_text) zurück.
"""
if not text: return [], ""
pairs = [] pairs = []
def _collect(m): def _collect(m):
k, t = (m.group("kind") or "").strip().lower(), (m.group("target") or "").strip() k, t = m.group("kind").strip().lower(), m.group("target").strip()
if k and t: pairs.append((k, t)) pairs.append((k, t))
return "" return ""
text = _REL_PIPE.sub(_collect, text) text = _REL_PIPE.sub(_collect, text)
text = _REL_SPACE.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 return pairs, text
def extract_callout_relations(text: str) -> Tuple[List[Tuple[str,str]], str]: 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 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): while i < len(lines):
m = _CALLOUT_START.match(lines[i]) line = lines[i]
m = _CALLOUT_START.match(line)
if not m: if not m:
keep_lines.append(lines[i]); i += 1; continue keep_lines.append(line)
block_lines = [m.group(1)] if m.group(1).strip() else [] 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 i += 1
while i < len(lines) and lines[i].lstrip().startswith('>'): 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: for bl in block_lines:
# 1. Prüfen auf explizites "Kind: Targets" (überschreibt Header-Typ für diese Zeile)
mrel = _REL_LINE.match(bl) mrel = _REL_LINE.match(bl)
if not mrel: continue if mrel:
kind, targets = mrel.group("kind").strip().lower(), mrel.group("targets") or "" line_kind = mrel.group("kind").strip().lower()
found = _WIKILINKS_IN_LINE.findall(targets) 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: if found:
for t in found: out_pairs.append((kind, t.strip())) if current_kind:
else: for t in found: out_pairs.append((current_kind, t.strip()))
for raw in re.split(r"[,;]", targets): else:
if raw.strip(): out_pairs.append((kind, raw.strip())) # 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) return out_pairs, "\n".join(keep_lines)
def extract_wikilinks(text: str) -> List[str]: def extract_wikilinks(text: str) -> List[str]:
"""Extrahiert Standard-Wikilinks.""" """Findet Standard-Wikilinks [[Target]] oder [[Alias|Target]]."""
return [m.group(1).strip() for m in _WIKILINK_RE.finditer(text or "")] 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 FILE: app/core/graph/graph_subgraph.py
DESCRIPTION: In-Memory Repräsentation eines Graphen für Scoring und Analyse. DESCRIPTION: In-Memory Repräsentation eines Graphen für Scoring und Analyse.
Zentrale Komponente für die Graph-Expansion (BFS) und Bonus-Berechnung. Zentrale Komponente für die Graph-Expansion (BFS) und Bonus-Berechnung.
MODULARISIERUNG: Teil des graph-Pakets (WP-14). WP-15c Update: Erhalt von Metadaten (target_section, provenance)
VERSION: 1.1.0 für präzises Retrieval-Reasoning.
VERSION: 1.2.0
STATUS: Active STATUS: Active
""" """
import math import math
@@ -22,6 +23,7 @@ class Subgraph:
""" """
def __init__(self) -> None: def __init__(self) -> None:
# adj speichert nun vollständige Payloads statt nur Tripel
self.adj: DefaultDict[str, List[Dict]] = defaultdict(list) self.adj: DefaultDict[str, List[Dict]] = defaultdict(list)
self.reverse_adj: DefaultDict[str, List[Dict]] = defaultdict(list) self.reverse_adj: DefaultDict[str, List[Dict]] = defaultdict(list)
self.in_degree: DefaultDict[str, int] = defaultdict(int) self.in_degree: DefaultDict[str, int] = defaultdict(int)
@@ -30,31 +32,49 @@ class Subgraph:
def add_edge(self, e: Dict) -> None: def add_edge(self, e: Dict) -> None:
""" """
Fügt eine Kante hinzu und aktualisiert Indizes. 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") src = e.get("source")
tgt = e.get("target") tgt = e.get("target")
kind = e.get("kind") 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") owner = e.get("note_id")
if not src or not tgt: if not src or not tgt:
return return
# 1. Forward-Kante # 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.out_degree[src] += 1
self.in_degree[tgt] += 1 self.in_degree[tgt] += 1
# 2. Reverse-Kante (für WP-04b Explanation Layer) # 2. Reverse-Kante (für Explanation Layer & Backlinks)
self.reverse_adj[tgt].append({"source": src, "kind": kind, "weight": weight}) self.reverse_adj[tgt].append(edge_data)
# 3. Kontext-Note Handling (erhöht die Zentralität der Parent-Note) # 3. Kontext-Note Handling (erhöht die Zentralität der Parent-Note)
if owner and owner != src: 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 self.out_degree[owner] += 1
if owner != tgt: 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 self.in_degree[owner] += 1
def aggregate_edge_bonus(self, node_id: str) -> float: def aggregate_edge_bonus(self, node_id: str) -> float:
@@ -73,14 +93,15 @@ class Subgraph:
indeg = self.in_degree.get(node_id, 0) indeg = self.in_degree.get(node_id, 0)
if indeg <= 0: if indeg <= 0:
return 0.0 return 0.0
# math.log1p(x) entspricht log(1+x)
return min(math.log1p(indeg) / 10.0, 0.15) return min(math.log1p(indeg) / 10.0, 0.15)
def get_outgoing_edges(self, node_id: str) -> List[Dict[str, Any]]: 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, []) return self.adj.get(node_id, [])
def get_incoming_edges(self, node_id: str) -> List[Dict[str, Any]]: 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, []) return self.reverse_adj.get(node_id, [])
@@ -111,13 +132,19 @@ def expand(
src, tgt = pl.get("source_id"), pl.get("target_id") src, tgt = pl.get("source_id"), pl.get("target_id")
if not src or not tgt: continue 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, "source": src,
"target": tgt, "target": tgt,
"kind": pl.get("kind", "edge"), "kind": pl.get("kind", "edge"),
"weight": calculate_edge_weight(pl), "weight": calculate_edge_weight(pl),
"note_id": pl.get("note_id"), "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 # BFS Logik: Neue Ziele in die nächste Frontier aufnehmen
if tgt not in visited: if tgt not in visited:
+35 -4
View File
@@ -1,10 +1,11 @@
""" """
FILE: app/core/graph/graph_utils.py FILE: app/core/graph/graph_utils.py
DESCRIPTION: Basale Werkzeuge, ID-Generierung und Provenance-Konfiguration für den Graphen. 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 os
import hashlib import hashlib
from typing import Iterable, List, Optional, Set, Any from typing import Iterable, List, Optional, Set, Any, Tuple
try: try:
import yaml import yaml
@@ -40,10 +41,19 @@ def _dedupe_seq(seq: Iterable[str]) -> List[str]:
seen.add(s); out.append(s) seen.add(s); out.append(s)
return out return out
def _mk_edge_id(kind: str, s: str, t: str, scope: str, rule_id: Optional[str] = None) -> str: 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.""" """
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}" 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() 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: 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) if extra: pl.update(extra)
return pl 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: def load_types_registry() -> dict:
"""Lädt die YAML-Registry.""" """Lädt die YAML-Registry."""
p = os.getenv("MINDNET_TYPES_FILE", "./config/types.yaml") p = os.getenv("MINDNET_TYPES_FILE", "./config/types.yaml")
+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. DESCRIPTION: Baut das JSON-Objekt für mindnet_notes.
FEATURES: FEATURES:
- Multi-Hash (body/full) für flexible Change Detection. - Multi-Hash (body/full) für flexible Change Detection.
- Fix v2.4.4: Integration der zentralen Registry (WP-14) für konsistente Defaults. - Fix v2.4.5: Präzise Hash-Logik für Profil-Änderungen.
VERSION: 2.4.4 - Integration der zentralen Registry (WP-14).
STATUS: Active
""" """
from __future__ import annotations from __future__ import annotations
from typing import Any, Dict, Tuple, Optional 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() return hashlib.sha256(content.encode("utf-8")).hexdigest()
def _get_hash_source_content(n: Dict[str, Any], mode: str) -> str: 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 == "body": return body
if mode == "full": if mode == "full":
fm = n.get("frontmatter") or {} fm = n.get("frontmatter") or {}
meta_parts = [] meta_parts = []
# Sortierte Liste für deterministische Hashes # Wir inkludieren alle Felder, die das Chunking oder Retrieval beeinflussen
for k in sorted(["title", "type", "status", "tags", "chunking_profile", "chunk_profile", "retriever_weight"]): # 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) val = fm.get(k)
if val is not None: meta_parts.append(f"{k}:{val}") if val is not None: meta_parts.append(f"{k}:{val}")
return f"{'|'.join(meta_parts)}||{body}" 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]: def make_note_payload(note: Any, *args, **kwargs) -> Dict[str, Any]:
""" """
Baut das Note-Payload inklusive Multi-Hash und Audit-Validierung. 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) n = _as_dict(note)
# Nutzt übergebene Registry oder lädt sie global # Registry & Context Settings
reg = kwargs.get("types_cfg") or load_type_registry() reg = kwargs.get("types_cfg") or load_type_registry()
hash_source = kwargs.get("hash_source", "parsed") hash_source = kwargs.get("hash_source", "parsed")
hash_normalize = kwargs.get("hash_normalize", "canonical") 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", {}) ingest_cfg = reg.get("ingestion_settings", {})
# --- retriever_weight Audit --- # --- retriever_weight Audit ---
# Priorität: Frontmatter -> Typ-Config -> globale Config -> Env-Var
default_rw = float(os.environ.get("MINDNET_DEFAULT_RETRIEVER_WEIGHT", 1.0)) default_rw = float(os.environ.get("MINDNET_DEFAULT_RETRIEVER_WEIGHT", 1.0))
retriever_weight = fm.get("retriever_weight") retriever_weight = fm.get("retriever_weight")
if retriever_weight is None: if retriever_weight is None:
@@ -107,14 +114,13 @@ def make_note_payload(note: Any, *args, **kwargs) -> Dict[str, Any]:
retriever_weight = default_rw retriever_weight = default_rw
# --- chunk_profile Audit --- # --- chunk_profile Audit ---
# Nutzt nun primär die ingestion_settings aus der Registry
chunk_profile = fm.get("chunking_profile") or fm.get("chunk_profile") chunk_profile = fm.get("chunking_profile") or fm.get("chunk_profile")
if chunk_profile is None: if chunk_profile is None:
chunk_profile = cfg_type.get("chunking_profile") or cfg_type.get("chunk_profile") chunk_profile = cfg_type.get("chunking_profile") or cfg_type.get("chunk_profile")
if chunk_profile is None: if chunk_profile is None:
chunk_profile = ingest_cfg.get("default_chunk_profile", cfg_def.get("chunking_profile", "sliding_standard")) 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") edge_defaults = fm.get("edge_defaults")
if edge_defaults is None: if edge_defaults is None:
edge_defaults = cfg_type.get("edge_defaults", cfg_def.get("edge_defaults", [])) 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 --- # --- MULTI-HASH ---
# Generiert Hashes für Change Detection # Generiert Hashes für Change Detection (WP-15b)
for mode in ["body", "full"]: for mode in ["body", "full"]:
content = _get_hash_source_content(n, mode) content = _get_hash_source_content(n, mode)
payload["hashes"][f"{mode}:{hash_source}:{hash_normalize}"] = _compute_hash(content) 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") tags = fm.get("tags") or fm.get("keywords") or n.get("tags")
if tags: payload["tags"] = _ensure_list(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"): for k in ("created", "modified", "date"):
v = fm.get(k) or n.get(k) v = fm.get(k) or n.get(k)
if v: payload[k] = str(v) 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 # Final JSON Validation Audit
json.loads(json.dumps(payload, ensure_ascii=False)) json.loads(json.dumps(payload, ensure_ascii=False))
+35 -10
View File
@@ -1,11 +1,11 @@
""" """
FILE: app/core/ingestion/ingestion_processor.py FILE: app/core/ingestion/ingestion_processor.py
DESCRIPTION: Der zentrale IngestionService (Orchestrator). 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-15b: Two-Pass Workflow mit globalem Kontext-Cache.
WP-20/22: Cloud-Resilienz und Content-Lifecycle integriert. WP-20/22: Cloud-Resilienz und Content-Lifecycle integriert.
AUDIT v2.13.10: Umstellung auf app.core.database Infrastruktur. AUDIT v2.14.0: Synchronisierung der Profil-Auflösung mit MoE-Experten.
VERSION: 2.13.10 VERSION: 2.14.0 (WP-25a: MoE & Profile Support)
STATUS: Active STATUS: Active
""" """
import logging import logging
@@ -55,11 +55,16 @@ class IngestionService:
# Synchronisierung der Konfiguration mit dem Instanz-Präfix # Synchronisierung der Konfiguration mit dem Instanz-Präfix
self.cfg.prefix = self.prefix self.cfg.prefix = self.prefix
self.client = get_client(self.cfg) self.client = get_client(self.cfg)
self.dim = self.settings.VECTOR_SIZE
self.registry = load_type_registry() self.registry = load_type_registry()
self.embedder = EmbeddingsClient() self.embedder = EmbeddingsClient()
self.llm = LLMService() 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.active_hash_mode = self.settings.CHANGE_DETECTION_MODE
self.batch_cache: Dict[str, NoteContext] = {} # WP-15b LocalBatchCache self.batch_cache: Dict[str, NoteContext] = {} # WP-15b LocalBatchCache
@@ -130,12 +135,18 @@ class IngestionService:
) )
note_id = note_pl["note_id"] 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) 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}" check_key = f"{self.active_hash_mode}:{hash_source}:{hash_normalize}"
old_hash = (old_payload or {}).get("hashes", {}).get(check_key) old_hash = (old_payload or {}).get("hashes", {}).get(check_key)
new_hash = note_pl.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) 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): 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} return {**result, "status": "unchanged", "note_id": note_id}
@@ -146,36 +157,46 @@ class IngestionService:
try: try:
body_text = getattr(parsed, "body", "") or "" body_text = getattr(parsed, "body", "") or ""
edge_registry.ensure_latest() 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) chunk_cfg = get_chunk_config_by_profile(self.registry, profile, note_type)
enable_smart = chunk_cfg.get("enable_smart_edge_allocation", False) 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) 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: for ch in chunks:
filtered = [] filtered = []
for cand in getattr(ch, "candidate_pool", []): 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 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) filtered.append(cand)
else: else:
# Explizite Kanten (Wikilinks/Callouts) werden ungeprüft übernommen
filtered.append(cand) filtered.append(cand)
ch.candidate_pool = filtered ch.candidate_pool = filtered
# Payload-Erstellung via interne Module # Payload-Erstellung für die Chunks
chunk_pls = make_chunk_payloads( chunk_pls = make_chunk_payloads(
fm, note_pl["path"], chunks, file_path=file_path, fm, note_pl["path"], chunks, file_path=file_path,
types_cfg=self.registry 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 [] 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( edges = build_edges_for_note(
note_id, chunk_pls, note_id, chunk_pls,
note_level_references=note_pl.get("references", []), note_level_references=note_pl.get("references", []),
include_note_scope_refs=note_scope_refs include_note_scope_refs=note_scope_refs
) )
# Kanten-Typen via Registry validieren/auflösen
for e in edges: for e in edges:
e["kind"] = edge_registry.resolve( e["kind"] = edge_registry.resolve(
e.get("kind", "related_to"), e.get("kind", "related_to"),
@@ -187,13 +208,16 @@ class IngestionService:
if purge_before and old_payload: if purge_before and old_payload:
purge_artifacts(self.client, self.prefix, note_id) 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) n_name, n_pts = points_for_note(self.prefix, note_pl, None, self.dim)
upsert_batch(self.client, n_name, n_pts) upsert_batch(self.client, n_name, n_pts)
# Speichern der Chunks
if chunk_pls and vecs: if chunk_pls and vecs:
c_pts = points_for_chunks(self.prefix, chunk_pls, vecs)[1] c_pts = points_for_chunks(self.prefix, chunk_pls, vecs)[1]
upsert_batch(self.client, f"{self.prefix}_chunks", c_pts) upsert_batch(self.client, f"{self.prefix}_chunks", c_pts)
# Speichern der Kanten
if edges: if edges:
e_pts = points_for_edges(self.prefix, edges)[1] e_pts = points_for_edges(self.prefix, edges)[1]
upsert_batch(self.client, f"{self.prefix}_edges", e_pts) 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: with open(target_path, "w", encoding="utf-8") as f:
f.write(markdown_content) f.write(markdown_content)
await asyncio.sleep(0.1) 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) return await self.process_file(file_path=target_path, vault_root=vault_root, apply=True, force_replace=True, purge_before=True)
+22 -8
View File
@@ -1,10 +1,16 @@
""" """
FILE: app/core/ingestion/ingestion_validation.py FILE: app/core/ingestion/ingestion_validation.py
DESCRIPTION: WP-15b semantische Validierung von Kanten gegen den LocalBatchCache. DESCRIPTION: WP-15b semantische Validierung von Kanten gegen den LocalBatchCache.
AUDIT v2.12.3: Integration der zentralen Text-Bereinigung (WP-14). WP-25a: Integration der Mixture of Experts (MoE) Profil-Steuerung.
VERSION: 2.13.0 (WP-25a: MoE & Profile Support)
STATUS: Active
FIX:
- Umstellung auf generate_raw_response mit profile_name="ingest_validator".
- Automatische Nutzung der Fallback-Kaskade (Cloud -> Lokal) via LLMService.
- Erhalt der sparsamen LLM-Nutzung (Validierung nur für Kandidaten-Pool).
""" """
import logging import logging
from typing import Dict, Any from typing import Dict, Any, Optional
from app.core.parser import NoteContext from app.core.parser import NoteContext
# ENTSCHEIDENDER FIX: Import der neutralen Bereinigungs-Logik zur Vermeidung von Circular Imports # ENTSCHEIDENDER FIX: Import der neutralen Bereinigungs-Logik zur Vermeidung von Circular Imports
@@ -17,11 +23,12 @@ async def validate_edge_candidate(
edge: Dict, edge: Dict,
batch_cache: Dict[str, NoteContext], batch_cache: Dict[str, NoteContext],
llm_service: Any, llm_service: Any,
provider: str provider: Optional[str] = None,
profile_name: str = "ingest_validator"
) -> bool: ) -> bool:
""" """
WP-15b: Validiert einen Kandidaten semantisch gegen das Ziel im Cache. WP-15b: Validiert einen Kandidaten semantisch gegen das Ziel im Cache.
Nutzt clean_llm_text zur Entfernung von Steuerzeichen vor der Auswertung. Nutzt das MoE-Profil 'ingest_validator' für deterministische YES/NO Prüfungen.
""" """
target_id = edge.get("to") target_id = edge.get("to")
target_ctx = batch_cache.get(target_id) target_ctx = batch_cache.get(target_id)
@@ -32,14 +39,16 @@ async def validate_edge_candidate(
target_ctx = batch_cache.get(base_id) target_ctx = batch_cache.get(base_id)
# Sicherheits-Fallback (Hard-Link Integrity) # Sicherheits-Fallback (Hard-Link Integrity)
# Explizite Wikilinks oder Callouts werden nicht durch das LLM verifiziert.
if not target_ctx: if not target_ctx:
logger.info(f"ℹ️ [VALIDATION SKIP] No context for '{target_id}' - allowing link.") logger.info(f"ℹ️ [VALIDATION SKIP] No context for '{target_id}' - allowing link.")
return True return True
# Prompt-Abruf (Nutzt Provider-String als Fallback-Key für die prompts.yaml)
template = llm_service.get_prompt("edge_validation", provider) template = llm_service.get_prompt("edge_validation", provider)
try: try:
logger.info(f"⚖️ [VALIDATING] Relation '{edge.get('kind')}' -> '{target_id}'...") logger.info(f"⚖️ [VALIDATING] Relation '{edge.get('kind')}' -> '{target_id}' (Profile: {profile_name})...")
prompt = template.format( prompt = template.format(
chunk_text=chunk_text[:1500], chunk_text=chunk_text[:1500],
target_title=target_ctx.title, target_title=target_ctx.title,
@@ -47,8 +56,13 @@ async def validate_edge_candidate(
edge_kind=edge.get("kind", "related_to") edge_kind=edge.get("kind", "related_to")
) )
# Die Antwort vom Service anfordern # WP-25a: Profilbasierter Aufruf (Delegiert Fallbacks an den Service)
raw_response = await llm_service.generate_raw_response(prompt, priority="background") # Nutzt ingest_validator (Cloud Mistral/Gemini -> Local Phi3:mini Kaskade)
raw_response = await llm_service.generate_raw_response(
prompt,
priority="background",
profile_name=profile_name
)
# WP-14 Fix: Zusätzliche Bereinigung zur Sicherstellung der Interpretierbarkeit # WP-14 Fix: Zusätzliche Bereinigung zur Sicherstellung der Interpretierbarkeit
response = clean_llm_text(raw_response) response = clean_llm_text(raw_response)
@@ -62,6 +76,6 @@ async def validate_edge_candidate(
logger.info(f"🚫 [REJECTED] Relation to '{target_id}' irrelevant for this chunk.") logger.info(f"🚫 [REJECTED] Relation to '{target_id}' irrelevant for this chunk.")
return is_valid return is_valid
except Exception as e: except Exception as e:
logger.warning(f"⚠️ Validation error for {target_id}: {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 # Im Zweifel (Timeout/Fehler) erlauben wir die Kante, um Datenverlust zu vermeiden
return True return True
+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}")
+260
View File
@@ -0,0 +1,260 @@
"""
FILE: app/core/retrieval/decision_engine.py
DESCRIPTION: Der Agentic Orchestrator für MindNet (WP-25a Edition).
Realisiert Multi-Stream Retrieval, Intent-basiertes Routing
und die neue Pre-Synthesis Kompression (Module A).
VERSION: 1.2.1 (WP-25a: Profile-Driven Orchestration & Optimized Cascade)
STATUS: Active
FIX:
- WP-25a: Volle Integration der Profil-Kaskade (Delegation an LLMService v3.5.2).
- WP-25a: Dynamische Nutzung des 'router_profile' für die Intent-Erkennung.
- WP-25a: Parallelisierte Kompression überlanger Wissens-Streams.
- WP-25: Beibehaltung von Stream-Tracing und Pre-Initialization Robustness.
- CLEANUP: Entfernung redundanter Fallback-Blocks (jetzt im LLMService).
"""
import asyncio
import logging
import yaml
import os
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": {}}
try:
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_engine.yaml: {e}")
return {"strategies": {}}
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)
# WP-25a: Diese Methode übernimmt nun auch die 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:
"""Nutzt den LLM-Router zur Wahl der Such-Strategie via router_profile."""
settings_cfg = self.config.get("settings", {})
prompt_key = settings_cfg.get("router_prompt_key", "intent_router_v1")
# WP-25a: Nutzt das spezialisierte Profil für das Routing
router_profile = settings_cfg.get("router_profile")
router_prompt_template = self.llm_service.get_prompt(prompt_key)
if not router_prompt_template:
return "FACT_WHAT"
full_prompt = router_prompt_template.format(query=query)
try:
# Der LLMService übernimmt hier über das Profil bereits die Fallback-Kaskade
response = await self.llm_service.generate_raw_response(
full_prompt, max_retries=1, priority="realtime", profile_name=router_profile
)
return str(response).strip().upper()
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).
WP-25a: MoE-Profile werden für die Kompression berücksichtigt.
"""
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 (Exceptions werden als Objekte zurückgegeben)
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 "[Fehler beim Abruf dieses Wissens-Streams]"
final_stream_tasks.append(_err())
continue
# Formatierung der Hits in Text
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-25a] Compressing stream '{name}' ({len(formatted_context)} chars)...")
comp_profile = stream_cfg.get("compression_profile")
final_stream_tasks.append(
self._compress_stream_content(name, formatted_context, query, comp_profile)
)
else:
# Direkt-Übernahme als Coroutine für gather()
async def _direct(c=formatted_context): return c
final_stream_tasks.append(_direct())
# Finale Inhalte (evtl. komprimiert) 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-25a Module A: Inhaltsverdichtung via Experten-Modell.
"""
compression_prompt = (
f"Du bist ein Wissens-Analyst. Reduziere den folgenden Wissens-Stream '{stream_name}' "
f"auf die Informationen, die für die Beantwortung der Frage '{query}' absolut notwendig sind.\n\n"
f"BEIBEHALTEN: Harte Fakten, Projektnamen, konkrete Werte und Quellenangaben.\n"
f"ENTFERNEN: Redundante Einleitungen, Füllwörter und irrelevante Details.\n\n"
f"STREAM-INHALT:\n{content}\n\n"
f"KOMPRIMIERTE ANALYSE:"
)
try:
summary = await self.llm_service.generate_raw_response(
compression_prompt,
profile_name=profile, # WP-25a: MoE Support
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 (WP-25)."""
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", {}),
explain=True
)
response = await self.retriever.search(request)
# WP-25: STREAM-TRACING
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 in diesem Stream 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:
"""Führt die finale Synthese basierend auf dem Strategie-Profil durch."""
# WP-25a: Nutzt das llm_profile der Strategie
profile = strategy.get("llm_profile")
template_key = strategy.get("prompt_template", "rag_template")
template = self.llm_service.get_prompt(template_key)
system_prompt = self.llm_service.get_prompt("system_prompt")
# WP-25 ROBUSTNESS: Pre-Initialization
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
prepend = strategy.get("prepend_instruction", "")
try:
final_prompt = template.format(**template_vars)
if prepend:
final_prompt = f"{prepend}\n\n{final_prompt}"
# WP-25a: MoE Call mit automatisierter Kaskade im LLMService
# (Frühere manuelle Fallback-Blocks wurden entfernt, da v3.5.2 dies intern löst)
response = await self.llm_service.generate_raw_response(
final_prompt, system=system_prompt, profile_name=profile, priority="realtime"
)
return response
except KeyError as e:
logger.error(f"Template Variable mismatch in '{template_key}': Missing {e}")
fallback_context = "\n\n".join([v for v in stream_results.values() if v])
# WP-25a FIX: Nutzt auch im Fallback das Strategie-Profil für Konsistenz
return await self.llm_service.generate_raw_response(
f"Beantworte: {query}\n\nKontext:\n{fallback_context}",
system=system_prompt, priority="realtime", profile_name=profile
)
except Exception as e:
logger.error(f"Final Synthesis failed: {e}")
return "Ich konnte keine Antwort generieren."
+92 -30
View File
@@ -1,9 +1,8 @@
""" """
FILE: app/core/retrieval/retriever.py FILE: app/core/retrieval/retriever.py
DESCRIPTION: Haupt-Schnittstelle für die Suche. Orchestriert Vektorsuche und Graph-Expansion. DESCRIPTION: Haupt-Schnittstelle für die Suche. Orchestriert Vektorsuche und Graph-Expansion.
Nutzt retriever_scoring.py für die WP-22 Logik. WP-15c Update: Note-Level Diversity Pooling & Super-Edge Aggregation.
MODULARISIERUNG: Verschoben in das retrieval-Paket für WP-14. VERSION: 0.7.0
VERSION: 0.6.16
STATUS: Active STATUS: Active
DEPENDENCIES: app.config, app.models.dto, app.core.database*, app.core.graph_adapter DEPENDENCIES: app.config, app.models.dto, app.core.database*, app.core.graph_adapter
""" """
@@ -13,6 +12,7 @@ import os
import time import time
import logging import logging
from typing import Any, Dict, List, Tuple, Iterable, Optional from typing import Any, Dict, List, Tuple, Iterable, Optional
from collections import defaultdict
from app.config import get_settings from app.config import get_settings
from app.models.dto import ( from app.models.dto import (
@@ -89,7 +89,6 @@ def _build_explanation(
) -> Explanation: ) -> Explanation:
""" """
Transformiert mathematische Scores und Graph-Signale in eine menschenlesbare Erklärung. Transformiert mathematische Scores und Graph-Signale in eine menschenlesbare Erklärung.
Behebt Pydantic ValidationErrors durch explizite String-Sicherung.
""" """
_, edge_w_cfg, _ = get_weights() _, edge_w_cfg, _ = get_weights()
base_val = scoring_debug["base_val"] base_val = scoring_debug["base_val"]
@@ -116,12 +115,22 @@ def _build_explanation(
elif semantic_score > 0.70: elif semantic_score > 0.70:
reasons.append(Reason(kind="semantic", message="Inhaltliche Übereinstimmung.", score_impact=base_val)) 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)) type_weight = float(payload.get("retriever_weight", 1.0))
if type_weight != 1.0: if type_weight != 1.0:
msg = "Bevorzugt" if type_weight > 1.0 else "De-priorisiert" 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))) 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) # 4. Kanten-Verarbeitung (Graph-Intelligence)
if subgraph and target_note_id and scoring_debug["edge_bonus"] > 0: if subgraph and target_note_id and scoring_debug["edge_bonus"] > 0:
raw_edges = [] raw_edges = []
@@ -131,7 +140,6 @@ def _build_explanation(
raw_edges.extend(subgraph.get_outgoing_edges(target_note_id) or []) raw_edges.extend(subgraph.get_outgoing_edges(target_note_id) or [])
for edge in raw_edges: for edge in raw_edges:
# FIX: Zwingende String-Konvertierung für Pydantic-Stabilität
src = str(edge.get("source") or "note_root") src = str(edge.get("source") or "note_root")
tgt = str(edge.get("target") or target_note_id or "unknown_target") tgt = str(edge.get("target") or target_note_id or "unknown_target")
kind = str(edge.get("kind", "related_to")) kind = str(edge.get("kind", "related_to"))
@@ -187,10 +195,14 @@ def _build_hits_from_semantic(
explain: bool = False, explain: bool = False,
dynamic_edge_boosts: Dict[str, float] = None dynamic_edge_boosts: Dict[str, float] = None
) -> QueryResponse: ) -> 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() t0 = time.time()
enriched = [] enriched = []
# Erstes Scoring für alle Kandidaten
for pid, semantic_score, payload in hits: for pid, semantic_score, payload in hits:
edge_bonus, cent_bonus = 0.0, 0.0 edge_bonus, cent_bonus = 0.0, 0.0
target_id = payload.get("note_id") target_id = payload.get("note_id")
@@ -202,15 +214,30 @@ def _build_hits_from_semantic(
except Exception: except Exception:
pass pass
# Mathematisches Scoring via WP-22 Engine
debug_data = compute_wp22_score( debug_data = compute_wp22_score(
semantic_score, payload, edge_bonus, cent_bonus, dynamic_edge_boosts semantic_score, payload, edge_bonus, cent_bonus, dynamic_edge_boosts
) )
enriched.append((pid, semantic_score, payload, debug_data)) 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) 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] = [] results: List[QueryHit] = []
for pid, s_score, pl, dbg in limited_hits: for pid, s_score, pl, dbg in limited_hits:
@@ -225,7 +252,6 @@ def _build_hits_from_semantic(
applied_boosts=dynamic_edge_boosts 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]") text_content = pl.get("page_content") or pl.get("text") or pl.get("content", "[Kein Text]")
results.append(QueryHit( results.append(QueryHit(
@@ -250,14 +276,14 @@ def _build_hits_from_semantic(
def hybrid_retrieve(req: QueryRequest) -> QueryResponse: def hybrid_retrieve(req: QueryRequest) -> QueryResponse:
""" """
Die Haupt-Einstiegsfunktion für die hybride Suche. 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() client, prefix = _get_client_and_prefix()
vector = list(req.query_vector) if req.query_vector else _get_query_vector(req) vector = list(req.query_vector) if req.query_vector else _get_query_vector(req)
top_k = req.top_k or 10 top_k = req.top_k or 10
# 1. Semantische Seed-Suche # 1. Semantische Seed-Suche (Wir laden etwas mehr für das Pooling)
hits = _semantic_hits(client, prefix, vector, top_k=top_k, filters=req.filters) hits = _semantic_hits(client, prefix, vector, top_k=top_k * 3, filters=req.filters)
# 2. Graph Expansion Konfiguration # 2. Graph Expansion Konfiguration
expand_cfg = req.expand if isinstance(req.expand, dict) else {} 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 subgraph: ga.Subgraph | None = None
if depth > 0 and hits: 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")}) seed_ids = list({h[2].get("note_id") for h in hits if h[2].get("note_id")})
if seed_ids: if seed_ids:
try: try:
# Subgraph aus RAM/DB laden
subgraph = ga.expand(client, prefix, seed_ids, depth=depth, edge_types=expand_cfg.get("edge_types")) 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 --- # --- WP-15c: Edge-Aggregation & Deduplizierung (Super-Kanten) ---
if subgraph and hasattr(subgraph, "graph"): # Verhindert Score-Explosion durch multiple Links auf versch. Abschnitte.
for _, _, data in subgraph.graph.edges(data=True): # Logik: 1. Kante zählt voll, weitere dämpfen auf Faktor 0.1.
# A. Provenance Weighting (WP-22 Bonus für Herkunft) if subgraph and hasattr(subgraph, "adj"):
prov = data.get("provenance", "rule") for src, edge_list in subgraph.adj.items():
# Belohnung: Explizite Links (1.0) > Smart (0.9) > Rule (0.7) # Gruppiere Kanten nach Ziel-Note (Deduplizierung ID_A -> ID_B)
prov_w = 1.0 if prov == "explicit" else (0.9 if prov == "smart" else 0.7) by_target = defaultdict(list)
for e in edge_list:
by_target[e["target"]].append(e)
# B. Intent Boost Multiplikator (Vom Router dynamisch injiziert) aggregated_list = []
kind = data.get("kind") for tgt, edges in by_target.items():
intent_multiplier = boost_edges.get(kind, 1.0) 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]
# Finales Gewicht setzen (Basis * Provenance * Intent) # Aggregiertes Gewicht berechnen (Sättigungs-Logik)
data["weight"] = data.get("weight", 1.0) * prov_w * intent_multiplier 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])
# 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: except Exception as e:
logger.error(f"Graph Expansion failed: {e}") logger.error(f"Graph Expansion failed: {e}")
subgraph = None subgraph = None
# 3. Scoring & Explanation Generierung # 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) return _build_hits_from_semantic(hits, top_k, "hybrid", subgraph, req.explain, boost_edges)
def semantic_retrieve(req: QueryRequest) -> QueryResponse: 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() client, prefix = _get_client_and_prefix()
vector = _get_query_vector(req) vector = _get_query_vector(req)
hits = _semantic_hits(client, prefix, vector, req.top_k or 10, req.filters) 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: class Retriever:
"""Schnittstelle für die asynchrone Suche.""" """Schnittstelle für die asynchrone Suche."""
async def search(self, request: QueryRequest) -> QueryResponse: async def search(self, request: QueryRequest) -> QueryResponse:
"""Führt eine hybride Suche aus."""
return hybrid_retrieve(request) return hybrid_retrieve(request)
+22 -20
View File
@@ -1,11 +1,10 @@
""" """
FILE: app/core/retrieval/retriever_scoring.py 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. Berechnet Relevanz-Scores basierend auf Semantik, Graph-Intelligence und Content Lifecycle.
MODULARISIERUNG: Verschoben in das retrieval-Paket für WP-14. FIX v1.0.3: Optimierte Interaktion zwischen Typ-Boost und Status-Dämpfung.
VERSION: 1.0.2 VERSION: 1.0.3
STATUS: Active STATUS: Active
DEPENDENCIES: app.config, typing
""" """
import os import os
import logging import logging
@@ -23,10 +22,6 @@ logger = logging.getLogger(__name__)
def get_weights() -> Tuple[float, float, float]: def get_weights() -> Tuple[float, float, float]:
""" """
Liefert die Basis-Gewichtung (semantic, edge, centrality) aus der Konfiguration. 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 from app.config import get_settings
settings = 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) - stable: 1.2 (Belohnung für verifiziertes Wissen)
- active: 1.0 (Standard-Gewichtung) - 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() status = str(payload.get("status", "active")).lower().strip()
if status == "stable": if status == "stable":
@@ -75,35 +70,42 @@ def compute_wp22_score(
dynamic_edge_boosts: Optional[Dict[str, float]] = None dynamic_edge_boosts: Optional[Dict[str, float]] = None
) -> Dict[str, Any]: ) -> Dict[str, Any]:
""" """
Die zentrale mathematische Scoring-Formel der Mindnet Intelligence. Die zentrale mathematische Scoring-Formel (WP-15c optimiert).
Implementiert das WP-22 Hybrid-Scoring (Semantic * Lifecycle * Graph). Implementiert das Hybrid-Scoring (Semantic * Lifecycle * Graph).
FORMEL: LOGIK:
Score = (Similarity * StatusMult) * (1 + (TypeWeight - 1) + ((EdgeW * EB + CentW * CB) * IntentBoost)) 1. Base = Similarity * StatusMult (Lifecycle-Filter).
2. Boosts = (TypeBoost - 1) + (GraphBoni * IntentFactor).
3. Final = Base * (1 + Boosts).
Returns: Der edge_bonus_raw enthält bereits die Super-Edge-Aggregation (WP-15c).
Dict mit dem finalen 'total' Score und allen mathematischen Zwischenwerten für den Explanation Layer.
""" """
sem_w, edge_w_cfg, cent_w_cfg = get_weights() sem_w, edge_w_cfg, cent_w_cfg = get_weights()
status_mult = get_status_multiplier(payload) 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)) node_weight = float(payload.get("retriever_weight", 1.0))
# 1. Berechnung des Base Scores (Semantik gewichtet durch Lifecycle-Status) # 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 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. # 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 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 # 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 edge_impact_final = (edge_w_cfg * edge_bonus_raw) * graph_boost_factor
cent_impact_final = (cent_w_cfg * cent_bonus_raw) * graph_boost_factor cent_impact_final = (cent_w_cfg * cent_bonus_raw) * graph_boost_factor
# 4. Finales Zusammenführen (Merging) # 4. Finales Zusammenführen (Merging)
# (node_weight - 1.0) sorgt dafür, dass ein Gewicht von 1.0 keinen Einfluss hat (neutral). # (node_weight - 1.0) wandelt das Gewicht in einen relativen Bonus um (z.B. 1.2 -> +0.2).
total = base_val * (1.0 + (node_weight - 1.0) + edge_impact_final + cent_impact_final) # 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) # Sicherstellen, dass der Score niemals 0 oder negativ ist (Floor)
final_score = max(0.0001, float(total)) final_score = max(0.0001, float(total))
@@ -114,7 +116,7 @@ def compute_wp22_score(
"cent_bonus": float(cent_bonus_raw), "cent_bonus": float(cent_bonus_raw),
"status_multiplier": status_mult, "status_multiplier": status_mult,
"graph_boost_factor": graph_boost_factor, "graph_boost_factor": graph_boost_factor,
"type_impact": node_weight - 1.0, "type_impact": type_impact,
"base_val": base_val, "base_val": base_val,
"edge_impact_final": edge_impact_final, "edge_impact_final": edge_impact_final,
"cent_impact_final": cent_impact_final "cent_impact_final": cent_impact_final
+207 -143
View File
@@ -1,10 +1,10 @@
""" """
FILE: app/frontend/ui_graph_service.py FILE: app/frontend/ui_graph_service.py
DESCRIPTION: Data Layer für den Graphen. Greift direkt auf Qdrant zu (Performance), um Knoten/Kanten zu laden und Texte zu rekonstruieren ("Stitching"). DESCRIPTION: Data Layer für den Graphen. Greift direkt auf Qdrant zu (Performance), um Knoten/Kanten zu laden und Texte zu rekonstruieren ("Stitching").
VERSION: 2.6.1 (Fix: Anchor-Link & Fragment Resolution) VERSION: 2.6.0
STATUS: Active STATUS: Active
DEPENDENCIES: qdrant_client, streamlit_agraph, ui_config, re DEPENDENCIES: qdrant_client, streamlit_agraph, ui_config, re
LAST_ANALYSIS: 2025-12-28 LAST_ANALYSIS: 2025-12-15
""" """
import re import re
@@ -24,7 +24,6 @@ class GraphExplorerService:
self.chunks_col = f"{self.prefix}_chunks" self.chunks_col = f"{self.prefix}_chunks"
self.edges_col = f"{self.prefix}_edges" self.edges_col = f"{self.prefix}_edges"
self._note_cache = {} self._note_cache = {}
self._ref_resolution_cache = {}
def get_note_with_full_content(self, note_id): def get_note_with_full_content(self, note_id):
""" """
@@ -38,7 +37,8 @@ class GraphExplorerService:
# 2. Volltext aus Chunks bauen # 2. Volltext aus Chunks bauen
full_text = self._fetch_full_text_stitched(note_id) full_text = self._fetch_full_text_stitched(note_id)
# 3. Ergebnis kombinieren (Kopie zurückgeben) # 3. Ergebnis kombinieren (Wir überschreiben das 'fulltext' Feld mit dem frischen Stitching)
# Wir geben eine Kopie zurück, um den Cache nicht zu verfälschen
complete_note = meta.copy() complete_note = meta.copy()
if full_text: if full_text:
complete_note['fulltext'] = full_text complete_note['fulltext'] = full_text
@@ -61,7 +61,7 @@ class GraphExplorerService:
# Initialset für Suche # Initialset für Suche
level_1_ids = {center_note_id} level_1_ids = {center_note_id}
# Suche Kanten für Center (L1) inkl. Titel für Anchor-Suche # Suche Kanten für Center (L1)
l1_edges = self._find_connected_edges([center_note_id], center_note.get("title")) l1_edges = self._find_connected_edges([center_note_id], center_note.get("title"))
for edge_data in l1_edges: for edge_data in l1_edges:
@@ -84,6 +84,7 @@ class GraphExplorerService:
if center_note_id in nodes_dict: if center_note_id in nodes_dict:
orig_title = nodes_dict[center_note_id].title orig_title = nodes_dict[center_note_id].title
clean_full = self._clean_markdown(center_text[:2000]) clean_full = self._clean_markdown(center_text[:2000])
# Wir packen den Text in den Tooltip (title attribute)
nodes_dict[center_note_id].title = f"{orig_title}\n\n📄 INHALT:\n{clean_full}..." nodes_dict[center_note_id].title = f"{orig_title}\n\n📄 INHALT:\n{clean_full}..."
# B. Previews für alle Nachbarn holen (Batch) # B. Previews für alle Nachbarn holen (Batch)
@@ -103,6 +104,8 @@ class GraphExplorerService:
prov = data['provenance'] prov = data['provenance']
color = get_edge_color(kind) color = get_edge_color(kind)
is_smart = (prov != "explicit" and prov != "rule") is_smart = (prov != "explicit" and prov != "rule")
# Label Logik
label_text = kind if show_labels else " " label_text = kind if show_labels else " "
final_edges.append(Edge( final_edges.append(Edge(
@@ -113,11 +116,15 @@ class GraphExplorerService:
return list(nodes_dict.values()), final_edges return list(nodes_dict.values()), final_edges
def _clean_markdown(self, text): def _clean_markdown(self, text):
"""Entfernt Markdown-Sonderzeichen für saubere Tooltips.""" """Entfernt Markdown-Sonderzeichen für saubere Tooltips im Browser."""
if not text: return "" if not text: return ""
# Entferne Header Marker (## )
text = re.sub(r'#+\s', '', text) text = re.sub(r'#+\s', '', text)
# Entferne Bold/Italic (** oder *)
text = re.sub(r'\*\*|__|\*|_', '', text) text = re.sub(r'\*\*|__|\*|_', '', text)
# Entferne Links [Text](Url) -> Text
text = re.sub(r'\[([^\]]+)\]\([^\)]+\)', r'\1', text) text = re.sub(r'\[([^\]]+)\]\([^\)]+\)', r'\1', text)
# Entferne Wikilinks [[Link]] -> Link
text = re.sub(r'\[\[([^\]]+)\]\]', r'\1', text) text = re.sub(r'\[\[([^\]]+)\]\]', r'\1', text)
return text return text
@@ -127,47 +134,52 @@ class GraphExplorerService:
scroll_filter = models.Filter( scroll_filter = models.Filter(
must=[models.FieldCondition(key="note_id", match=models.MatchValue(value=note_id))] must=[models.FieldCondition(key="note_id", match=models.MatchValue(value=note_id))]
) )
# Limit hoch genug setzen
chunks, _ = self.client.scroll(self.chunks_col, scroll_filter=scroll_filter, limit=100, with_payload=True) chunks, _ = self.client.scroll(self.chunks_col, scroll_filter=scroll_filter, limit=100, with_payload=True)
# Sortieren nach 'ord' (Reihenfolge im Dokument)
chunks.sort(key=lambda x: x.payload.get('ord', 999)) chunks.sort(key=lambda x: x.payload.get('ord', 999))
full_text = [c.payload.get('text', '') for c in chunks if c.payload.get('text')]
full_text = []
for c in chunks:
# 'text' ist der reine Inhalt ohne Overlap
txt = c.payload.get('text', '')
if txt: full_text.append(txt)
return "\n\n".join(full_text) return "\n\n".join(full_text)
except: except:
return "Fehler beim Laden des Volltexts." return "Fehler beim Laden des Volltexts."
def _fetch_previews_for_nodes(self, node_ids): def _fetch_previews_for_nodes(self, node_ids):
""" """Holt Batch-weise den ersten Chunk für eine Liste von Nodes."""
Holt Batch-weise den ersten relevanten Textabschnitt für eine Liste von Nodes. if not node_ids: return {}
Optimiert die Ladezeit durch Reduzierung der API-Calls.
"""
if not node_ids:
return {}
previews = {} previews = {}
try: try:
scroll_filter = models.Filter( scroll_filter = models.Filter(must=[models.FieldCondition(key="note_id", match=models.MatchAny(any=node_ids))])
must=[models.FieldCondition(key="note_id", match=models.MatchAny(any=node_ids))] # Limit = Anzahl Nodes * 3 (Puffer)
)
# Genügend Chunks laden, um für jede ID eine Vorschau zu finden
chunks, _ = self.client.scroll(self.chunks_col, scroll_filter=scroll_filter, limit=len(node_ids)*3, with_payload=True) chunks, _ = self.client.scroll(self.chunks_col, scroll_filter=scroll_filter, limit=len(node_ids)*3, with_payload=True)
for c in chunks: for c in chunks:
nid = c.payload.get("note_id") nid = c.payload.get("note_id")
# Wir nehmen den ersten gefundenen Chunk # Nur den ersten gefundenen Chunk pro Note nehmen
if nid and nid not in previews: if nid and nid not in previews:
previews[nid] = c.payload.get("window") or c.payload.get("text") or "" previews[nid] = c.payload.get("window") or c.payload.get("text") or ""
except Exception: except: pass
pass
return previews return previews
def _find_connected_edges(self, note_ids, note_title=None): def _find_connected_edges(self, note_ids, note_title=None):
""" """
Findet ein- und ausgehende Kanten für eine Liste von IDs. Findet eingehende und ausgehende Kanten.
Implementiert den Fix für Anker-Links [[Titel#Abschnitt]] durch Präfix-Suche in der target_id.
WICHTIG: target_id enthält nur den Titel (ohne #Abschnitt).
target_section ist ein separates Feld für Abschnitt-Informationen.
""" """
results = [] results = []
if not note_ids: if not note_ids:
return results return results
# 1. AUSGEHENDE KANTEN (Outgoing) # 1. OUTGOING EDGES (Der "Owner"-Fix)
# Suche über 'note_id' als Besitzer der Kante. # 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.
out_filter = models.Filter(must=[ out_filter = models.Filter(must=[
models.FieldCondition(key="note_id", match=models.MatchAny(any=note_ids)), models.FieldCondition(key="note_id", match=models.MatchAny(any=note_ids)),
models.FieldCondition(key="kind", match=models.MatchExcept(**{"except": SYSTEM_EDGES})) models.FieldCondition(key="kind", match=models.MatchExcept(**{"except": SYSTEM_EDGES}))
@@ -175,71 +187,79 @@ class GraphExplorerService:
res_out, _ = self.client.scroll(self.edges_col, scroll_filter=out_filter, limit=2000, with_payload=True) res_out, _ = self.client.scroll(self.edges_col, scroll_filter=out_filter, limit=2000, with_payload=True)
results.extend(res_out) results.extend(res_out)
# 2. EINGEHENDE KANTEN (Incoming) # 2. INCOMING EDGES (Ziel = Chunk ID, Note ID oder Titel)
# Suche über target_id (Ziel der Kante). # WICHTIG: target_id enthält nur den Titel, target_section ist separat
# Sammele alle Chunk-IDs für exakte Treffer auf Segment-Ebene # Chunk IDs der aktuellen Notes holen
c_filter = models.Filter(must=[models.FieldCondition(key="note_id", match=models.MatchAny(any=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=1000, with_payload=False) chunks, _ = self.client.scroll(self.chunks_col, scroll_filter=c_filter, limit=1000, with_payload=False)
chunk_ids = [c.id for c in chunks] chunk_ids = [c.id for c in chunks]
should_conditions = [] shoulds = []
# Case A: Edge zeigt auf einen unserer Chunks
if chunk_ids: if chunk_ids:
should_conditions.append(models.FieldCondition(key="target_id", match=models.MatchAny(any=chunk_ids))) shoulds.append(models.FieldCondition(key="target_id", match=models.MatchAny(any=chunk_ids)))
should_conditions.append(models.FieldCondition(key="target_id", match=models.MatchAny(any=note_ids)))
# TITEL-BASIERTE SUCHE (Inkl. Anker-Fix) # Case B: Edge zeigt direkt auf unsere Note ID
titles_to_check = [] 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: if note_title:
titles_to_check.append(note_title) titles_to_search.append(note_title)
# Aliase laden für robuste Verlinkung
for nid in note_ids:
note = self._fetch_note_cached(nid)
if note:
aliases = note.get("aliases", [])
if isinstance(aliases, str): aliases = [aliases]
titles_to_check.extend([a for a in aliases if a not in titles_to_check])
# Exakte Titel-Matches hinzufügen # Lade auch Titel aus den Notes selbst (falls note_title nicht übergeben wurde)
for t in titles_to_check: for nid in note_ids:
should_conditions.append(models.FieldCondition(key="target_id", match=models.MatchValue(value=t))) 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)
if should_conditions: # 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( in_filter = models.Filter(
must=[models.FieldCondition(key="kind", match=models.MatchExcept(**{"except": SYSTEM_EDGES}))], must=[models.FieldCondition(key="kind", match=models.MatchExcept(**{"except": SYSTEM_EDGES}))],
should=should_conditions should=shoulds
) )
res_in, _ = self.client.scroll(self.edges_col, scroll_filter=in_filter, limit=2000, with_payload=True) res_in, _ = self.client.scroll(self.edges_col, scroll_filter=in_filter, limit=2000, with_payload=True)
results.extend(res_in) results.extend(res_in)
# FIX FÜR [[Titel#Abschnitt]]: Suche nach Fragmenten
if titles_to_check:
for t in titles_to_check:
anchor_filter = models.Filter(must=[
models.FieldCondition(key="target_id", match=models.MatchText(text=t)),
models.FieldCondition(key="kind", match=models.MatchExcept(**{"except": SYSTEM_EDGES}))
])
res_anchor, _ = self.client.scroll(self.edges_col, scroll_filter=anchor_filter, limit=1000, with_payload=True)
existing_ids = {r.id for r in results}
for edge in res_anchor:
tgt = edge.payload.get("target_id", "")
# Client-seitige Filterung: Nur Kanten nehmen, die mit Titel# beginnen
if edge.id not in existing_ids and (tgt == t or tgt.startswith(f"{t}#")):
results.append(edge)
return results return results
def _find_connected_edges_batch(self, note_ids): def _find_connected_edges_batch(self, note_ids):
"""Wrapper für die Suche in tieferen Ebenen des Graphen.""" """
first_note = self._fetch_note_cached(note_ids[0]) if note_ids else None Wrapper für Level 2 Suche.
title = first_note.get("title") if first_note else None Lädt Titel der ersten Note für Titel-basierte Suche.
return self._find_connected_edges(note_ids, note_title=title) """
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): def _process_edge(self, record, nodes_dict, unique_edges, current_depth):
""" """
Verarbeitet eine rohe Kante, löst Quell- und Ziel-Referenzen auf Verarbeitet eine rohe Edge, löst IDs auf und fügt sie den Dictionaries hinzu.
und fügt sie den Dictionaries für den Graphen 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: if not record or not record.payload:
return None, None return None, None
@@ -250,10 +270,13 @@ class GraphExplorerService:
kind = payload.get("kind") kind = payload.get("kind")
provenance = payload.get("provenance", "explicit") provenance = payload.get("provenance", "explicit")
# Prüfe, ob beide Referenzen vorhanden sind
if not src_ref or not tgt_ref: if not src_ref or not tgt_ref:
return None, None return None, None
# IDs zu Notes auflösen (Hier greift der Fragment-Fix) # 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) src_note = self._resolve_note_from_ref(src_ref)
tgt_note = self._resolve_note_from_ref(tgt_ref) tgt_note = self._resolve_note_from_ref(tgt_ref)
@@ -261,118 +284,159 @@ class GraphExplorerService:
src_id = src_note.get('note_id') src_id = src_note.get('note_id')
tgt_id = tgt_note.get('note_id') tgt_id = tgt_note.get('note_id')
if src_id and tgt_id and src_id != tgt_id: # Prüfe, ob beide IDs vorhanden sind
# Knoten zum Set hinzufügen if not src_id or not tgt_id:
return None, None
if src_id != tgt_id:
# Nodes hinzufügen
self._add_node_to_dict(nodes_dict, src_note, level=current_depth) self._add_node_to_dict(nodes_dict, src_note, level=current_depth)
self._add_node_to_dict(nodes_dict, tgt_note, level=current_depth) self._add_node_to_dict(nodes_dict, tgt_note, level=current_depth)
# Kante registrieren (Deduplizierung) # Kante hinzufügen (mit Deduplizierung)
key = (src_id, tgt_id) key = (src_id, tgt_id)
existing = unique_edges.get(key) existing = unique_edges.get(key)
is_current_explicit = (provenance in ["explicit", "rule"])
should_update = True should_update = True
# Bevorzuge explizite Kanten vor Smart Kanten
is_current_explicit = (provenance in ["explicit", "rule"])
if existing: if existing:
is_existing_explicit = (existing.get('provenance', '') in ["explicit", "rule"]) is_existing_explicit = (existing.get('provenance', '') in ["explicit", "rule"])
if is_existing_explicit and not is_current_explicit: if is_existing_explicit and not is_current_explicit:
should_update = False should_update = False
if should_update: if should_update:
unique_edges[key] = { unique_edges[key] = {"source": src_id, "target": tgt_id, "kind": kind, "provenance": provenance}
"source": src_id,
"target": tgt_id,
"kind": kind,
"provenance": provenance
}
return src_id, tgt_id return src_id, tgt_id
return None, None return None, None
def _fetch_note_cached(self, note_id): def _fetch_note_cached(self, note_id):
"""Lädt eine Note aus Qdrant mit Session-Caching.""" if note_id in self._note_cache: return self._note_cache[note_id]
if not note_id: res, _ = self.client.scroll(
return None collection_name=self.notes_col,
if note_id in self._note_cache: scroll_filter=models.Filter(must=[models.FieldCondition(key="note_id", match=models.MatchValue(value=note_id))]),
return self._note_cache[note_id] limit=1, with_payload=True
)
try: if res:
res, _ = self.client.scroll( self._note_cache[note_id] = res[0].payload
collection_name=self.notes_col, return res[0].payload
scroll_filter=models.Filter(must=[
models.FieldCondition(key="note_id", match=models.MatchValue(value=note_id))
]),
limit=1, with_payload=True
)
if res and res[0].payload:
payload = res[0].payload
self._note_cache[note_id] = payload
return payload
except Exception:
pass
return None return None
def _resolve_note_from_ref(self, ref_str): def _resolve_note_from_ref(self, ref_str):
""" """
Löst eine Referenz (ID, Chunk-ID oder Wikilink mit Anker) auf eine Note auf. Löst eine Referenz zu einer Note Payload auf.
Bereinigt Anker (#) vor der Suche.
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: if not ref_str:
return None return None
if ref_str in self._ref_resolution_cache: # Fall A: Enthält # (kann Chunk-ID oder Titel#Abschnitt sein)
return self._ref_resolution_cache[ref_str]
# Fragment-Behandlung: Trenne Anker ab
base_ref = ref_str.split("#")[0].strip()
# 1. Versuch: Direkte Note-ID Suche
note = self._fetch_note_cached(base_ref)
if note:
self._ref_resolution_cache[ref_str] = note
return note
# 2. Versuch: Titel-Suche (Keyword-Match)
try:
res, _ = self.client.scroll(
collection_name=self.notes_col,
scroll_filter=models.Filter(must=[
models.FieldCondition(key="title", match=models.MatchValue(value=base_ref))
]),
limit=1, with_payload=True
)
if res and res[0].payload:
payload = res[0].payload
self._ref_resolution_cache[ref_str] = payload
return payload
except Exception:
pass
# 3. Versuch: Auflösung über Chunks
if "#" in ref_str: if "#" in ref_str:
try: try:
res_chunk = self.client.retrieve(self.chunks_col, ids=[ref_str], with_payload=True) # Versuch 1: Chunk ID direkt (Format: note_id#c01)
if res_chunk and res_chunk[0].payload: res = self.client.retrieve(self.chunks_col, ids=[ref_str], with_payload=True)
note_id = res_chunk[0].payload.get("note_id") if res and res[0].payload:
note = self._fetch_note_cached(note_id) note_id = res[0].payload.get("note_id")
if note: if note_id:
self._ref_resolution_cache[ref_str] = note return self._fetch_note_cached(note_id)
return note except:
except Exception:
pass pass
# 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
note = self._fetch_note_cached(ref_str)
if note:
return note
# 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))
]),
limit=1, with_payload=True
)
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 return None
def _add_node_to_dict(self, node_dict, note_payload, level=1): def _add_node_to_dict(self, node_dict, note_payload, level=1):
"""Erstellt ein Node-Objekt für streamlit-agraph mit Styling."""
nid = note_payload.get("note_id") nid = note_payload.get("note_id")
if not nid or nid in node_dict: if not nid or nid in node_dict: return
return
ntype = note_payload.get("type", "default") ntype = note_payload.get("type", "default")
color = GRAPH_COLORS.get(ntype, GRAPH_COLORS.get("default", "#8395a7")) color = GRAPH_COLORS.get(ntype, GRAPH_COLORS["default"])
# Basis-Tooltip (wird später erweitert)
tooltip = f"Titel: {note_payload.get('title')}\nTyp: {ntype}" tooltip = f"Titel: {note_payload.get('title')}\nTyp: {ntype}"
size = 45 if level == 0 else (25 if level == 1 else 15) if level == 0: size = 45
elif level == 1: size = 25
else: size = 15
node_dict[nid] = Node( node_dict[nid] = Node(
id=nid, id=nid,
label=note_payload.get('title', nid), label=note_payload.get('title', nid),
+97 -20
View File
@@ -1,25 +1,29 @@
""" """
FILE: app/main.py FILE: app/main.py
DESCRIPTION: Bootstrap der FastAPI Anwendung. Inkludiert Router und Middleware. DESCRIPTION: Bootstrap der FastAPI Anwendung für WP-25a (Agentic MoE).
VERSION: 0.6.0 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 STATUS: Active
DEPENDENCIES: app.config, app.routers.* (embed, qdrant, query, graph, tools, feedback, chat, ingest, admin) DEPENDENCIES: app.config, app.routers.*, app.services.llm_service
LAST_ANALYSIS: 2025-12-15
""" """
from __future__ import annotations from __future__ import annotations
from fastapi import FastAPI import logging
from .config import get_settings import os
#from .routers.embed_router import router as embed_router from contextlib import asynccontextmanager
#from .routers.qdrant_router import router as qdrant_router 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.query import router as query_router
from .routers.graph import router as graph_router from .routers.graph import router as graph_router
from .routers.tools import router as tools_router from .routers.tools import router as tools_router
from .routers.feedback import router as feedback_router from .routers.feedback import router as feedback_router
# NEU: Chat Router (WP-05)
from .routers.chat import router as chat_router from .routers.chat import router as chat_router
# NEU: Ingest Router (WP-11)
from .routers.ingest import router as ingest_router from .routers.ingest import router as ingest_router
try: try:
@@ -27,26 +31,98 @@ try:
except Exception: except Exception:
admin_router = None 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: 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() 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") @app.get("/healthz")
def healthz(): def healthz():
return {"status": "ok", "qdrant": s.QDRANT_URL, "prefix": s.COLLECTION_PREFIX} """Bietet Statusinformationen über die Engine und Datenbank-Verbindung."""
return {
# app.include_router(embed_router) "status": "ok",
# app.include_router(qdrant_router) "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(query_router, prefix="/query", tags=["query"])
app.include_router(graph_router, prefix="/graph", tags=["graph"]) app.include_router(graph_router, prefix="/graph", tags=["graph"])
app.include_router(tools_router, prefix="/tools", tags=["tools"]) app.include_router(tools_router, prefix="/tools", tags=["tools"])
app.include_router(feedback_router, prefix="/feedback", tags=["feedback"]) app.include_router(feedback_router, prefix="/feedback", tags=["feedback"])
app.include_router(chat_router, prefix="/chat", tags=["chat"]) # WP-25a Agentic Chat
# NEU: Chat Endpoint
app.include_router(chat_router, prefix="/chat", tags=["chat"])
# NEU: Ingest Endpoint
app.include_router(ingest_router, prefix="/ingest", tags=["ingest"]) app.include_router(ingest_router, prefix="/ingest", tags=["ingest"])
if admin_router: if admin_router:
@@ -54,4 +130,5 @@ def create_app() -> FastAPI:
return app return app
# Instanziierung der App
app = create_app() app = create_app()
+28 -22
View File
@@ -1,10 +1,9 @@
""" """
FILE: app/models/dto.py FILE: app/models/dto.py
DESCRIPTION: Pydantic-Modelle (DTOs) für Request/Response Bodies. Definiert das API-Schema. 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 STATUS: Active
DEPENDENCIES: pydantic, typing, uuid DEPENDENCIES: pydantic, typing, uuid
LAST_ANALYSIS: 2025-12-18
""" """
from __future__ import annotations from __future__ import annotations
@@ -12,8 +11,14 @@ from pydantic import BaseModel, Field
from typing import List, Literal, Optional, Dict, Any from typing import List, Literal, Optional, Dict, Any
import uuid import uuid
# Gültige Kanten-Typen gemäß Manual # 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"] 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 --- # --- Basis-DTOs ---
@@ -43,13 +48,14 @@ class EdgeDTO(BaseModel):
direction: Literal["out", "in", "undirected"] = "out" direction: Literal["out", "in", "undirected"] = "out"
provenance: Optional[Literal["explicit", "rule", "smart", "structure"]] = "explicit" provenance: Optional[Literal["explicit", "rule", "smart", "structure"]] = "explicit"
confidence: float = 1.0 confidence: float = 1.0
target_section: Optional[str] = None
# --- Request Models --- # --- Request Models ---
class QueryRequest(BaseModel): class QueryRequest(BaseModel):
""" """
Request für /query. Request für /query. Unterstützt Multi-Stream Isolation via filters.
""" """
mode: Literal["semantic", "edge", "hybrid"] = "hybrid" mode: Literal["semantic", "edge", "hybrid"] = "hybrid"
query: Optional[str] = None query: Optional[str] = None
@@ -60,14 +66,12 @@ class QueryRequest(BaseModel):
ret: Dict = {"with_paths": True, "with_notes": True, "with_chunks": True} ret: Dict = {"with_paths": True, "with_notes": True, "with_chunks": True}
explain: bool = False explain: bool = False
# WP-22: Semantic Graph Routing # WP-22/25: Dynamische Gewichtung der Graphen-Highways
boost_edges: Optional[Dict[str, float]] = None boost_edges: Optional[Dict[str, float]] = None
class FeedbackRequest(BaseModel): class FeedbackRequest(BaseModel):
""" """User-Feedback zu einem spezifischen Treffer oder der Gesamtantwort."""
User-Feedback zu einem spezifischen Treffer oder der Gesamtantwort (WP-08 Basis).
"""
query_id: str = Field(..., description="ID der ursprünglichen Suche") query_id: str = Field(..., description="ID der ursprünglichen Suche")
node_id: str = Field(..., description="ID des bewerteten Treffers oder 'generated_answer'") 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)") score: int = Field(..., ge=1, le=5, description="1 (Irrelevant) bis 5 (Perfekt)")
@@ -75,16 +79,14 @@ class FeedbackRequest(BaseModel):
class ChatRequest(BaseModel): class ChatRequest(BaseModel):
""" """Request für /chat (WP-25 Einstieg)."""
WP-05: Request für /chat.
"""
message: str = Field(..., description="Die Nachricht des Users") message: str = Field(..., description="Die Nachricht des Users")
conversation_id: Optional[str] = Field(None, description="ID für Chat-Verlauf") conversation_id: Optional[str] = Field(None, description="ID für Chat-Verlauf")
top_k: int = 5 top_k: int = 5
explain: bool = False explain: bool = False
# --- WP-04b Explanation Models --- # --- Explanation Models ---
class ScoreBreakdown(BaseModel): class ScoreBreakdown(BaseModel):
"""Aufschlüsselung der Score-Komponenten nach der WP-22 Formel.""" """Aufschlüsselung der Score-Komponenten nach der WP-22 Formel."""
@@ -95,14 +97,14 @@ class ScoreBreakdown(BaseModel):
raw_edge_bonus: float raw_edge_bonus: float
raw_centrality: float raw_centrality: float
node_weight: float node_weight: float
# WP-22 Debug Fields für Messbarkeit
status_multiplier: float = 1.0 status_multiplier: float = 1.0
graph_boost_factor: float = 1.0 graph_boost_factor: float = 1.0
class Reason(BaseModel): class Reason(BaseModel):
"""Ein semantischer Grund für das Ranking.""" """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 message: str
score_impact: Optional[float] = None score_impact: Optional[float] = None
details: Optional[Dict[str, Any]] = None details: Optional[Dict[str, Any]] = None
@@ -113,7 +115,6 @@ class Explanation(BaseModel):
breakdown: ScoreBreakdown breakdown: ScoreBreakdown
reasons: List[Reason] reasons: List[Reason]
related_edges: Optional[List[EdgeDTO]] = None related_edges: Optional[List[EdgeDTO]] = None
# WP-22 Debug: Verifizierung des Routings
applied_intent: Optional[str] = None applied_intent: Optional[str] = None
applied_boosts: Optional[Dict[str, float]] = None applied_boosts: Optional[Dict[str, float]] = None
@@ -121,7 +122,10 @@ class Explanation(BaseModel):
# --- Response Models --- # --- Response Models ---
class QueryHit(BaseModel): 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 node_id: str
note_id: str note_id: str
semantic_score: float semantic_score: float
@@ -132,10 +136,11 @@ class QueryHit(BaseModel):
source: Optional[Dict] = None source: Optional[Dict] = None
payload: Optional[Dict] = None payload: Optional[Dict] = None
explanation: Optional[Explanation] = None explanation: Optional[Explanation] = None
stream_origin: Optional[str] = Field(None, description="Name des Ursprungs-Streams")
class QueryResponse(BaseModel): 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())) query_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
results: List[QueryHit] results: List[QueryHit]
used_mode: str used_mode: str
@@ -152,11 +157,12 @@ class GraphResponse(BaseModel):
class ChatResponse(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") query_id: str = Field(..., description="Traceability ID")
answer: str = Field(..., description="Generierte Antwort vom LLM") 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 latency_ms: int
intent: Optional[str] = Field("FACT", description="WP-06: Erkannter Intent") intent: Optional[str] = Field("FACT", description="Die gewählte WP-25 Strategie")
intent_source: Optional[str] = Field("Unknown", description="Quelle der Intent-Erkennung") intent_source: Optional[str] = Field("LLM_Router", description="Quelle der Intent-Erkennung")
+110 -248
View File
@@ -1,12 +1,15 @@
""" """
FILE: app/routers/chat.py FILE: app/routers/chat.py
DESCRIPTION: Haupt-Chat-Interface (RAG & Interview). Enthält Intent-Router (Keywords/LLM) und Prompt-Construction. DESCRIPTION: Haupt-Chat-Interface (WP-25a Agentic Edition).
VERSION: 2.7.8 (Full Unabridged Stability Edition) Kombiniert die spezialisierte Interview-Logik und Keyword-Erkennung
mit der neuen MoE-Orchestrierung und Pre-Synthesis Kompression.
VERSION: 3.0.4 (WP-25a: Optimized MoE & Cascade Delegation)
STATUS: Active STATUS: Active
FIX: FIX:
1. Implementiert Context-Throttling für Ollama (MAX_OLLAMA_CHARS). - WP-25a: Delegation der Fallback-Kaskade an den LLMService (v3.5.2).
2. Deaktiviert LLM-Retries für den Chat (max_retries=0). - WP-25a: Nutzung der zentralisierten Stream-Kompression der DecisionEngine (v1.2.1).
3. Behebt Double-Fallback-Schleifen und Silent Refusals. - WP-25a: Konsistente Nutzung von MoE-Profilen für Interview- und RAG-Modus.
- 100% Erhalt der v3.0.2 Logik (Interview, Schema-Resolution, FastPaths).
""" """
from fastapi import APIRouter, HTTPException, Depends from fastapi import APIRouter, HTTPException, Depends
@@ -16,50 +19,44 @@ import uuid
import logging import logging
import yaml import yaml
import os import os
import asyncio
from pathlib import Path from pathlib import Path
from app.config import get_settings 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.services.llm_service import LLMService
from app.core.retrieval.retriever import Retriever
from app.services.feedback_service import log_search from app.services.feedback_service import log_search
router = APIRouter() router = APIRouter()
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
# --- Helper: Config Loader --- # --- EBENE 1: CONFIG LOADER & CACHING (WP-25 Standard) ---
_DECISION_CONFIG_CACHE = None _DECISION_CONFIG_CACHE = None
_TYPES_CONFIG_CACHE = None _TYPES_CONFIG_CACHE = None
def _load_decision_config() -> Dict[str, Any]: def _load_decision_config() -> Dict[str, Any]:
"""Lädt die Strategie-Konfiguration."""
settings = get_settings() settings = get_settings()
path = Path(settings.DECISION_CONFIG_PATH) 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: try:
with open(path, "r", encoding="utf-8") as f: if path.exists():
return yaml.safe_load(f) with open(path, "r", encoding="utf-8") as f:
return yaml.safe_load(f) or {}
except Exception as e: except Exception as e:
logger.error(f"Failed to load decision config: {e}") logger.error(f"Failed to load decision config: {e}")
return default_config return {"strategies": {}}
def _load_types_config() -> Dict[str, Any]: 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") path = os.getenv("MINDNET_TYPES_FILE", "config/types.yaml")
try: try:
with open(path, "r", encoding="utf-8") as f: if os.path.exists(path):
return yaml.safe_load(f) or {} with open(path, "r", encoding="utf-8") as f:
except Exception: return yaml.safe_load(f) or {}
return {} except Exception as e:
logger.error(f"Failed to load types config: {e}")
return {}
def get_full_config() -> Dict[str, Any]: def get_full_config() -> Dict[str, Any]:
global _DECISION_CONFIG_CACHE global _DECISION_CONFIG_CACHE
@@ -76,21 +73,17 @@ def get_types_config() -> Dict[str, Any]:
def get_decision_strategy(intent: str) -> Dict[str, Any]: def get_decision_strategy(intent: str) -> Dict[str, Any]:
config = get_full_config() config = get_full_config()
strategies = config.get("strategies", {}) 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: def _detect_target_type(message: str, configured_schemas: Dict[str, Any]) -> str:
""" """WP-07: Identifiziert den gewünschten Notiz-Typ (Keyword-basiert)."""
Versucht zu erraten, welchen Notiz-Typ der User erstellen will.
Nutzt Keywords aus types.yaml UND Mappings.
"""
message_lower = message.lower() message_lower = message.lower()
# 1. Check types.yaml detection_keywords (Priority!)
types_cfg = get_types_config() types_cfg = get_types_config()
types_def = types_cfg.get("types", {}) types_def = types_cfg.get("types", {})
# 1. Check types.yaml detection_keywords
for type_name, type_data in types_def.items(): for type_name, type_data in types_def.items():
keywords = type_data.get("detection_keywords", []) keywords = type_data.get("detection_keywords", [])
for kw in keywords: for kw in keywords:
@@ -103,293 +96,162 @@ def _detect_target_type(message: str, configured_schemas: Dict[str, Any]) -> str
if type_key in message_lower: if type_key in message_lower:
return type_key return type_key
# 3. Synonym-Mapping (Legacy Fallback) # 3. Synonym-Mapping (Legacy)
synonyms = { synonyms = {
"projekt": "project", "vorhaben": "project", "projekt": "project", "entscheidung": "decision", "ziel": "goal",
"entscheidung": "decision", "beschluss": "decision", "erfahrung": "experience", "wert": "value", "prinzip": "principle"
"ziel": "goal",
"erfahrung": "experience", "lektion": "experience",
"wert": "value",
"prinzip": "principle",
"notiz": "default", "idee": "default"
} }
for term, schema_key in synonyms.items(): for term, schema_key in synonyms.items():
if term in message_lower: if term in message_lower:
return schema_key return schema_key
return "default" 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: 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() q = query.strip().lower()
if "?" in q: return True if "?" in q: return True
starters = ["wer", "wie", "was", "wo", "wann", "warum", "weshalb", "wozu", "welche", "bist du"]
# W-Fragen Indikatoren return any(q.startswith(s + " ") for s in starters)
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
async def _classify_intent(query: str, llm: LLMService) -> tuple[str, str]: async def _classify_intent(query: str, llm: LLMService) -> tuple[str, str]:
""" """Hybrid Router: Keyword-Fast-Paths & DecisionEngine LLM Router."""
Hybrid Router v5:
1. Decision Keywords (Strategie) -> Prio 1
2. Type Keywords (Interview Trigger) -> Prio 2
3. LLM (Fallback) -> Prio 3
"""
config = get_full_config() config = get_full_config()
strategies = config.get("strategies", {}) strategies = config.get("strategies", {})
settings = config.get("settings", {})
query_lower = query.lower() query_lower = query.lower()
# 1. FAST PATH A: Strategie Keywords # 1. FAST PATH: Keyword Trigger
for intent_name, strategy in strategies.items(): for intent_name, strategy in strategies.items():
if intent_name == "FACT": continue
keywords = strategy.get("trigger_keywords", []) keywords = strategy.get("trigger_keywords", [])
for k in keywords: for k in keywords:
if k.lower() in query_lower: if k.lower() in query_lower:
return intent_name, "Keyword (Strategy)" return intent_name, "Keyword (FastPath)"
# 2. FAST PATH B: Type Keywords -> INTERVIEW # 2. FAST PATH B: Type Keywords -> INTERVIEW
if not _is_question(query_lower): if not _is_question(query_lower):
types_cfg = get_types_config() types_cfg = get_types_config()
types_def = types_cfg.get("types", {}) for type_name, type_data in types_cfg.get("types", {}).items():
for kw in type_data.get("detection_keywords", []):
for type_name, type_data in types_def.items():
keywords = type_data.get("detection_keywords", [])
for kw in keywords:
if kw.lower() in query_lower: if kw.lower() in query_lower:
return "INTERVIEW", f"Keyword (Type: {type_name})" return "INTERVIEW", "Keyword (Interview)"
# 3. SLOW PATH: LLM Router # 3. SLOW PATH: DecisionEngine LLM Router (MoE-gesteuert)
if settings.get("llm_fallback_enabled", False): intent = await llm.decision_engine._determine_strategy(query)
router_prompt_template = llm.get_prompt("llm_router_prompt") return intent, "DecisionEngine (LLM)"
if router_prompt_template: # --- EBENE 3: RETRIEVAL AGGREGATION ---
prompt = router_prompt_template.replace("{query}", query)
logger.info("Keywords failed (or Question detected). Asking LLM for Intent...")
try: def _collect_all_hits(stream_responses: Dict[str, Any]) -> List[QueryHit]:
# FIX: Auch beim Routing keine Retries im Chat-Fluss """Sammelt deduplizierte Treffer aus allen Streams für das Tracing."""
raw_response = await llm.generate_raw_response(prompt, priority="realtime", max_retries=0) all_hits = []
llm_output_upper = raw_response.upper() seen_node_ids = set()
for _, response in stream_responses.items():
# In v3.0.4 sammeln wir die 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)
if "INTERVIEW" in llm_output_upper or "CREATE" in llm_output_upper: # --- EBENE 4: ENDPUNKT ---
return "INTERVIEW", "LLM Router"
for strat_key in strategies.keys(): def get_llm_service():
if strat_key in llm_output_upper: return LLMService()
return strat_key, "LLM Router"
except Exception as e:
logger.error(f"Router LLM failed: {e}")
return "FACT", "Default (No Match)"
@router.post("/", response_model=ChatResponse) @router.post("/", response_model=ChatResponse)
async def chat_endpoint( async def chat_endpoint(
request: ChatRequest, request: ChatRequest,
llm: LLMService = Depends(get_llm_service), llm: LLMService = Depends(get_llm_service)
retriever: Retriever = Depends(get_retriever)
): ):
start_time = time.time() start_time = time.time()
query_id = str(uuid.uuid4()) query_id = str(uuid.uuid4())
logger.info(f"Chat request [{query_id}]: {request.message[:50]}...") settings = get_settings()
logger.info(f"🚀 [WP-25a] Chat request [{query_id}]: {request.message[:50]}...")
try: try:
# 1. Intent Detection # 1. Intent Detection
intent, intent_source = await _classify_intent(request.message, llm) 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) strategy = get_decision_strategy(intent)
prompt_key = strategy.get("prompt_template", "rag_template") engine = llm.decision_engine
preferred_provider = strategy.get("preferred_provider")
sources_hits = [] sources_hits = []
final_prompt = "" answer_text = ""
context_str = ""
# 2. INTERVIEW MODE (Bitgenaue WP-07 Logik)
if intent == "INTERVIEW": if intent == "INTERVIEW":
# --- INTERVIEW MODE ---
target_type = _detect_target_type(request.message, strategy.get("schemas", {})) target_type = _detect_target_type(request.message, strategy.get("schemas", {}))
types_cfg = get_types_config() types_cfg = get_types_config()
type_def = types_cfg.get("types", {}).get(target_type, {}) type_def = types_cfg.get("types", {}).get(target_type, {})
fields_list = type_def.get("schema", []) fields_list = type_def.get("schema", [])
# WP-07: Restaurierte Fallback Logik
if not fields_list: if not fields_list:
configured_schemas = strategy.get("schemas", {}) configured_schemas = strategy.get("schemas", {})
fallback_schema = configured_schemas.get(target_type, configured_schemas.get("default")) fallback = configured_schemas.get(target_type, configured_schemas.get("default", {}))
if isinstance(fallback_schema, dict): fields_list = fallback.get("fields", []) if isinstance(fallback, dict) else (fallback or [])
fields_list = fallback_schema.get("fields", [])
else:
fields_list = fallback_schema or []
logger.info(f"[{query_id}] Interview Type: {target_type}. Fields: {len(fields_list)}")
fields_str = "\n- " + "\n- ".join(fields_list) fields_str = "\n- " + "\n- ".join(fields_list)
template = llm.get_prompt(strategy.get("prompt_template", "interview_template"))
template = llm.get_prompt(prompt_key) final_prompt = template.replace("{query}", request.message) \
final_prompt = template.replace("{context_str}", "Dialogverlauf...") \
.replace("{query}", request.message) \
.replace("{target_type}", target_type) \ .replace("{target_type}", target_type) \
.replace("{schema_fields}", fields_str) \ .replace("{schema_fields}", fields_str)
.replace("{schema_hint}", "")
# WP-25a: MoE Call (Kaskade erfolgt intern im LLMService)
answer_text = await llm.generate_raw_response(
final_prompt, system=llm.get_prompt("system_prompt"),
priority="realtime", profile_name="compression_fast", max_retries=0
)
sources_hits = [] sources_hits = []
# 3. RAG MODE (Optimierte MoE Orchestrierung)
else: else:
# --- RAG MODE (FACT, DECISION, EMPATHY, CODING) --- # Phase A & B: Retrieval & Kompression (Delegation an Engine v1.2.1)
inject_types = strategy.get("inject_types", []) # Diese Methode gibt bereits die (evtl. komprimierten) Kontext-Strings zurück.
prepend_instr = strategy.get("prepend_instruction", "") formatted_context_map = await engine._execute_parallel_streams(strategy, request.message)
edge_boosts = strategy.get("edge_boosts", {})
query_req = QueryRequest( # Erfassung der Quellen für das Tracing
query=request.message, raw_stream_map = {}
mode="hybrid", stream_keys = strategy.get("use_streams", [])
top_k=request.top_k, library = engine.config.get("streams_library", {})
explain=request.explain,
boost_edges=edge_boosts 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
answer_text = await engine._generate_final_answer(
intent, strategy, request.message, formatted_context_map
) )
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
answer_text = await llm.generate_raw_response(
prompt=final_prompt,
system=system_prompt,
priority="realtime",
provider=preferred_provider,
max_retries=0
)
except Exception as e:
logger.error(f"🛑 [{query_id}] Primary Provider '{preferred_provider}' failed: {e}")
# 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...")
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."
duration_ms = int((time.time() - start_time) * 1000) duration_ms = int((time.time() - start_time) * 1000)
# Logging # Logging (WP-15)
try: try:
log_search( log_search(
query_id=query_id, query_id=query_id, query_text=request.message, results=sources_hits,
query_text=request.message, mode=f"wp25a_{intent.lower()}", metadata={"strategy": intent, "source": intent_source}
results=sources_hits,
mode="interview" if intent == "INTERVIEW" else "chat_rag",
metadata={"intent": intent, "source": intent_source, "provider": preferred_provider}
) )
except: pass except: pass
return ChatResponse( return ChatResponse(
query_id=query_id, query_id=query_id, answer=answer_text, sources=sources_hits,
answer=answer_text, latency_ms=duration_ms, intent=intent, intent_source=intent_source
sources=sources_hits,
latency_ms=duration_ms,
intent=intent,
intent_source=intent_source
) )
except Exception as e: except Exception as e:
logger.error(f"Error in chat endpoint: {e}", exc_info=True) logger.error(f"❌ Chat Endpoint Failure: {e}", exc_info=True)
# Wir geben eine benutzerfreundliche Meldung zurück, statt nur den Error-Stack raise HTTPException(status_code=500, detail="Fehler bei der Verarbeitung der Anfrage.")
raise HTTPException(status_code=500, detail="Das System konnte die Anfrage nicht verarbeiten.")
+72 -22
View File
@@ -1,40 +1,74 @@
""" """
FILE: app/services/embeddings_client.py FILE: app/services/embeddings_client.py
DESCRIPTION: Unified Embedding Client. Nutzt Ollama API (HTTP). Ersetzt lokale sentence-transformers. DESCRIPTION: Unified Embedding Client. Nutzt MoE-Profile zur Modellsteuerung.
VERSION: 2.5.0 WP-25a: Integration der llm_profiles.yaml für konsistente Vektoren.
VERSION: 2.6.0 (WP-25a: MoE & Profile Support)
STATUS: Active STATUS: Active
DEPENDENCIES: httpx, requests, app.config DEPENDENCIES: httpx, requests, app.config, yaml
LAST_ANALYSIS: 2025-12-15
""" """
from __future__ import annotations from __future__ import annotations
import os import os
import logging import logging
import httpx import httpx
import requests # Für den synchronen Fallback import requests
from typing import List import yaml
from pathlib import Path
from typing import List, Dict, Any
from app.config import get_settings from app.config import get_settings
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
class EmbeddingsClient: 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): def __init__(self):
self.settings = get_settings() 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: if not self.model:
self.model = os.getenv("MINDNET_LLM_MODEL", "phi3:mini") 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]: async def embed_query(self, text: str) -> List[float]:
"""Erzeugt einen Vektor für eine Suchanfrage."""
return await self._request_embedding(text) return await self._request_embedding(text)
async def embed_documents(self, texts: List[str]) -> List[List[float]]: async def embed_documents(self, texts: List[str]) -> List[List[float]]:
"""Erzeugt Vektoren für einen Batch von Dokumenten."""
vectors = [] 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: async with httpx.AsyncClient(timeout=120.0) as client:
for text in texts: for text in texts:
vec = await self._request_embedding_with_client(client, text) vec = await self._request_embedding_with_client(client, text)
@@ -42,18 +76,23 @@ class EmbeddingsClient:
return vectors return vectors
async def _request_embedding(self, text: str) -> List[float]: async def _request_embedding(self, text: str) -> List[float]:
"""Interner Request-Handler für Einzelabfragen."""
async with httpx.AsyncClient(timeout=30.0) as client: async with httpx.AsyncClient(timeout=30.0) as client:
return await self._request_embedding_with_client(client, text) return await self._request_embedding_with_client(client, text)
async def _request_embedding_with_client(self, client: httpx.AsyncClient, text: str) -> List[float]: 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" url = f"{self.base_url}/api/embeddings"
try: try:
# WP-25: Aktuell optimiert für Ollama-API Struktur
response = await client.post(url, json={"model": self.model, "prompt": text}) response = await client.post(url, json={"model": self.model, "prompt": text})
response.raise_for_status() response.raise_for_status()
return response.json().get("embedding", []) return response.json().get("embedding", [])
except Exception as e: except Exception as e:
logger.error(f"Async embedding failed: {e}") logger.error(f"Async embedding failed (Model: {self.model}): {e}")
return [] return []
# ============================================================================== # ==============================================================================
@@ -62,27 +101,38 @@ class EmbeddingsClient:
def embed_text(text: str) -> List[float]: def embed_text(text: str) -> List[float]:
""" """
LEGACY/SYNC: Nutzt jetzt ebenfalls OLLAMA via 'requests'. LEGACY/SYNC: Nutzt ebenfalls die Profil-Logik für Konsistenz.
Ersetzt SentenceTransformers, um Dimensionskonflikte (768 vs 384) zu lösen. Ersetzt lokale sentence-transformers zur Vermeidung von Dimensionskonflikten.
""" """
if not text or not text.strip(): if not text or not text.strip():
return [] return []
base_url = os.getenv("MINDNET_OLLAMA_URL", "http://127.0.0.1:11434") settings = get_settings()
model = os.getenv("MINDNET_EMBEDDING_MODEL")
# 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
# Fallback logik identisch zur Klasse
if not model: if not model:
model = os.getenv("MINDNET_LLM_MODEL", "phi3:mini") model = os.getenv("MINDNET_LLM_MODEL", "phi3:mini")
url = f"{base_url}/api/embeddings" url = f"{base_url}/api/embeddings"
try: try:
# Synchroner Request (blockierend) # Synchroner Request via requests
response = requests.post(url, json={"model": model, "prompt": text}, timeout=30) response = requests.post(url, json={"model": model, "prompt": text}, timeout=30)
response.raise_for_status() response.raise_for_status()
data = response.json() return response.json().get("embedding", [])
return data.get("embedding", [])
except Exception as e: except Exception as e:
logger.error(f"Sync embedding (Ollama) failed: {e}") logger.error(f"Sync embedding failed (Model: {model}): {e}")
return [] return []
+155 -136
View File
@@ -1,16 +1,14 @@
""" """
FILE: app/services/llm_service.py FILE: app/services/llm_service.py
DESCRIPTION: Hybrid-Client für Ollama, Google GenAI (Gemini) und OpenRouter. DESCRIPTION: Hybrid-Client für Ollama, Google GenAI (Gemini) und OpenRouter.
Verwaltet provider-spezifische Prompts und Background-Last. WP-25a: Implementierung der Mixture of Experts (MoE) Kaskaden-Steuerung.
WP-20: Optimiertes Fallback-Management zum Schutz von Cloud-Quoten. VERSION: 3.5.2 (WP-25a: MoE & Fallback Cascade Support)
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
STATUS: Active STATUS: Active
FIX: FIX:
- Importiert clean_llm_text von app.core.registry zur Vermeidung von Circular Imports. - WP-25a: Implementierung der rekursiven Fallback-Kaskade via fallback_profile.
- Wendet clean_llm_text auf Text-Antworten in generate_raw_response an. - WP-25a: Schutz gegen zirkuläre Profil-Referenzen (visited_profiles).
- WP-25a: Erweitertes Logging für Tracing der Experten-Entscheidungen.
- Erhalt der Ingest-Stability (WP-25) und des Rate-Limit-Managements.
""" """
import httpx import httpx
import yaml import yaml
@@ -19,26 +17,28 @@ import asyncio
import json import json
from google import genai from google import genai
from google.genai import types from google.genai import types
from openai import AsyncOpenAI # Für OpenRouter (OpenAI-kompatibel) from openai import AsyncOpenAI
from pathlib import Path from pathlib import Path
from typing import Optional, Dict, Any, Literal from typing import Optional, Dict, Any, Literal
from app.config import get_settings 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 from app.core.registry import clean_llm_text
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
class LLMService: class LLMService:
# GLOBALER SEMAPHOR für Hintergrund-Last Steuerung (WP-06)
_background_semaphore = None _background_semaphore = None
def __init__(self): def __init__(self):
self.settings = get_settings() self.settings = get_settings()
self.prompts = self._load_prompts() self.prompts = self._load_prompts()
# Initialisiere Semaphore einmalig auf Klassen-Ebene # WP-25a: Zentrale Experten-Profile laden
self.profiles = self._load_llm_profiles()
self._decision_engine = None
if LLMService._background_semaphore is None: if LLMService._background_semaphore is None:
limit = getattr(self.settings, "BACKGROUND_LIMIT", 2) limit = getattr(self.settings, "BACKGROUND_LIMIT", 2)
logger.info(f"🚦 LLMService: Initializing Background Semaphore with limit: {limit}") logger.info(f"🚦 LLMService: Initializing Background Semaphore with limit: {limit}")
@@ -50,10 +50,9 @@ class LLMService:
timeout=httpx.Timeout(self.settings.LLM_TIMEOUT) timeout=httpx.Timeout(self.settings.LLM_TIMEOUT)
) )
# 2. Google GenAI Client (Modern SDK) # 2. Google GenAI Client
self.google_client = None self.google_client = None
if self.settings.GOOGLE_API_KEY: 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( self.google_client = genai.Client(
api_key=self.settings.GOOGLE_API_KEY, api_key=self.settings.GOOGLE_API_KEY,
http_options={'api_version': 'v1'} http_options={'api_version': 'v1'}
@@ -66,16 +65,20 @@ class LLMService:
self.openrouter_client = AsyncOpenAI( self.openrouter_client = AsyncOpenAI(
base_url="https://openrouter.ai/api/v1", base_url="https://openrouter.ai/api/v1",
api_key=self.settings.OPENROUTER_API_KEY, api_key=self.settings.OPENROUTER_API_KEY,
# Strikter Timeout für OpenRouter Free-Tier zur Vermeidung von Hangs.
timeout=45.0 timeout=45.0
) )
logger.info("🛰️ LLMService: OpenRouter Integration active.") 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: def _load_prompts(self) -> dict:
"""Lädt die Prompt-Konfiguration aus der YAML-Datei."""
path = Path(self.settings.PROMPTS_PATH) path = Path(self.settings.PROMPTS_PATH)
if not path.exists(): if not path.exists():
logger.error(f"❌ Prompts file not found at {path}")
return {} return {}
try: try:
with open(path, "r", encoding="utf-8") as f: with open(path, "r", encoding="utf-8") as f:
@@ -84,25 +87,27 @@ class LLMService:
logger.error(f"❌ Failed to load prompts: {e}") logger.error(f"❌ Failed to load prompts: {e}")
return {} return {}
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}. System will use .env defaults.")
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, provider: str = None) -> str: def get_prompt(self, key: str, 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).
"""
active_provider = provider or self.settings.MINDNET_LLM_PROVIDER active_provider = provider or self.settings.MINDNET_LLM_PROVIDER
data = self.prompts.get(key, "") data = self.prompts.get(key, "")
if isinstance(data, dict): if isinstance(data, dict):
# Wir versuchen erst den Provider, dann Gemini, dann Ollama
val = data.get(active_provider, data.get("gemini", data.get("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(val)
return str(data) return str(data)
async def generate_raw_response( async def generate_raw_response(
@@ -117,31 +122,83 @@ class LLMService:
model_override: Optional[str] = None, model_override: Optional[str] = None,
json_schema: Optional[Dict[str, Any]] = None, json_schema: Optional[Dict[str, Any]] = None,
json_schema_name: str = "mindnet_json", 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: ) -> str:
""" """
Haupteinstiegspunkt für LLM-Anfragen mit Priorisierung. Haupteinstiegspunkt für LLM-Anfragen mit rekursiver Kaskaden-Logik.
Wendet die Bereinigung auf Text-Antworten an.
""" """
target_provider = provider or self.settings.MINDNET_LLM_PROVIDER visited_profiles = visited_profiles or []
target_provider = provider
target_model = model_override
target_temp = None
fallback_profile = None
if priority == "background": # 1. Profil-Auflösung
async with LLMService._background_semaphore: 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!")
# Fallback auf Standard-Provider falls nichts übergeben/definiert wurde
if not target_provider:
target_provider = self.settings.MINDNET_LLM_PROVIDER
logger.info(f"ℹ️ Kein Provider/Profil definiert. Nutze Default: {target_provider}")
# 2. Ausführung mit Fehler-Handling für Kaskade
try:
if priority == "background":
async with LLMService._background_semaphore:
res = await self._dispatch(
target_provider, 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( res = await self._dispatch(
target_provider, prompt, system, force_json, target_provider, prompt, system, force_json,
max_retries, base_delay, model_override, max_retries, base_delay, target_model,
json_schema, json_schema_name, strict_json_schema json_schema, json_schema_name, strict_json_schema, target_temp
) )
# WP-14 Fix: Bereinige Text-Antworten vor Rückgabe
# 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 chain.")
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}")
# 3. Kaskaden-Logik: Nächstes Profil in der Kette versuchen
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, system=system, force_json=force_json,
max_retries=max_retries, base_delay=base_delay,
priority=priority, provider=provider, model_override=model_override,
json_schema=json_schema, json_schema_name=json_schema_name,
strict_json_schema=strict_json_schema,
profile_name=fallback_profile,
visited_profiles=visited_profiles
)
# 4. 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(prompt, system, force_json, max_retries, base_delay)
return clean_llm_text(res) if not force_json else res return clean_llm_text(res) if not force_json else res
res = await self._dispatch( raise e
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
async def _dispatch( async def _dispatch(
self, self,
@@ -154,14 +211,11 @@ class LLMService:
model_override: Optional[str], model_override: Optional[str],
json_schema: Optional[Dict[str, Any]], json_schema: Optional[Dict[str, Any]],
json_schema_name: str, json_schema_name: str,
strict_json_schema: bool strict_json_schema: bool,
temperature: Optional[float] = None
) -> str: ) -> str:
""" """Routet die Anfrage an den spezifischen Provider-Executor."""
Routet die Anfrage mit intelligenter Rate-Limit Erkennung.
Nutzt max_retries um die Rate-Limit Schleife zu begrenzen.
"""
rate_limit_attempts = 0 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)) 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) wait_time = getattr(self.settings, "LLM_RATE_LIMIT_WAIT", 60.0)
@@ -169,52 +223,41 @@ class LLMService:
try: try:
if provider == "openrouter" and self.openrouter_client: if provider == "openrouter" and self.openrouter_client:
return await self._execute_openrouter( return await self._execute_openrouter(
prompt=prompt, prompt=prompt, system=system, force_json=force_json,
system=system, model_override=model_override, json_schema=json_schema,
force_json=force_json, json_schema_name=json_schema_name, strict_json_schema=strict_json_schema,
model_override=model_override, temperature=temperature
json_schema=json_schema,
json_schema_name=json_schema_name,
strict_json_schema=strict_json_schema
) )
if provider == "gemini" and self.google_client: 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, temperature)
return await self._execute_ollama(prompt, system, force_json, max_retries, base_delay)
except Exception as e: except Exception as e:
err_str = str(e) err_str = str(e)
# Intelligente 429 Erkennung # Rate-Limit Handling (429)
is_rate_limit = any(x in err_str for x in ["429", "RESOURCE_EXHAUSTED", "rate_limited", "Too Many Requests"]) if any(x in err_str for x in ["429", "RESOURCE_EXHAUSTED", "rate_limited"]):
if is_rate_limit and rate_limit_attempts < max_rate_retries:
rate_limit_attempts += 1 rate_limit_attempts += 1
logger.warning( logger.warning(f"⏳ Rate Limit {provider}. Attempt {rate_limit_attempts}. Wait {wait_time}s.")
f"⏳ [LLMService] Rate Limit detected from {provider}. "
f"Attempt {rate_limit_attempts}/{max_rate_retries}. Waiting {wait_time}s..."
)
await asyncio.sleep(wait_time) await asyncio.sleep(wait_time)
continue continue
# Andere Fehler werden an generate_raw_response für die Kaskade gereicht
# 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 raise e
async def _execute_google(self, prompt, system, force_json, model_override): async def _execute_google(self, prompt, system, force_json, model_override, temperature):
"""Native Google SDK Integration (Gemini) mit v1 Fix."""
model = model_override or self.settings.GEMINI_MODEL model = model_override or self.settings.GEMINI_MODEL
clean_model = model.replace("models/", "") clean_model = model.replace("models/", "")
config = types.GenerateContentConfig( config_kwargs = {
system_instruction=system, "system_instruction": system,
response_mime_type="application/json" if force_json else "text/plain" "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( response = await asyncio.wait_for(
asyncio.to_thread( asyncio.to_thread(
self.google_client.models.generate_content, self.google_client.models.generate_content,
@@ -225,58 +268,51 @@ class LLMService:
return response.text.strip() return response.text.strip()
async def _execute_openrouter( async def _execute_openrouter(
self, self, prompt: str, system: Optional[str], force_json: bool,
prompt: str, model_override: Optional[str], json_schema: Optional[Dict[str, Any]] = None,
system: Optional[str], json_schema_name: str = "mindnet_json", strict_json_schema: bool = True,
force_json: bool, temperature: Optional[float] = None
model_override: Optional[str],
json_schema: Optional[Dict[str, Any]] = None,
json_schema_name: str = "mindnet_json",
strict_json_schema: bool = True
) -> str: ) -> str:
"""OpenRouter API Integration (OpenAI-kompatibel)."""
model = model_override or self.settings.OPENROUTER_MODEL model = model_override or self.settings.OPENROUTER_MODEL
logger.info(f"🛰️ OpenRouter Call: Model='{model}' | Temp={temperature}")
messages = [] messages = []
if system: if system: messages.append({"role": "system", "content": system})
messages.append({"role": "system", "content": system})
messages.append({"role": "user", "content": prompt}) messages.append({"role": "user", "content": prompt})
kwargs: Dict[str, Any] = {} kwargs: Dict[str, Any] = {}
if temperature is not None:
kwargs["temperature"] = temperature
if force_json: if force_json:
if json_schema: if json_schema:
kwargs["response_format"] = { kwargs["response_format"] = {
"type": "json_schema", "type": "json_schema",
"json_schema": { "json_schema": {"name": json_schema_name, "strict": strict_json_schema, "schema": json_schema}
"name": json_schema_name,
"strict": strict_json_schema,
"schema": json_schema
}
} }
else: else:
kwargs["response_format"] = {"type": "json_object"} kwargs["response_format"] = {"type": "json_object"}
response = await self.openrouter_client.chat.completions.create( response = await self.openrouter_client.chat.completions.create(
model=model, model=model, messages=messages, **kwargs
messages=messages,
**kwargs
) )
return response.choices[0].message.content.strip()
async def _execute_ollama(self, prompt, system, force_json, max_retries, base_delay): if not response.choices:
"""Lokaler Ollama Call mit striktem Retry-Limit.""" 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, temperature=None):
# Nutzt Profil-Temperatur oder strikte Defaults für lokale Hardware-Schonung
effective_temp = temperature if temperature is not None else (0.1 if force_json else 0.7)
payload = { payload = {
"model": self.settings.LLM_MODEL, "model": self.settings.LLM_MODEL,
"prompt": prompt, "prompt": prompt,
"stream": False, "stream": False,
"options": { "options": {"temperature": effective_temp, "num_ctx": 8192}
"temperature": 0.1 if force_json else 0.7,
"num_ctx": 8192 # Begrenzung für Stabilität (WP-20)
}
} }
if force_json: if force_json: payload["format"] = "json"
payload["format"] = "json" if system: payload["system"] = system
if system:
payload["system"] = system
attempt = 0 attempt = 0
while True: while True:
@@ -286,32 +322,15 @@ class LLMService:
return res.json().get("response", "").strip() return res.json().get("response", "").strip()
except Exception as e: except Exception as e:
attempt += 1 attempt += 1
# WICHTIG: Wenn max_retries=0 (Chat), bricht dies nach dem 1. Versuch (attempt=1) sofort ab.
if attempt > max_retries: if attempt > max_retries:
logger.error(f"❌ Ollama request failed after {attempt} attempt(s): {e}") logger.error(f"❌ Ollama final failure after {attempt} attempts: {e}")
raise e raise e
await asyncio.sleep(base_delay * (2 ** (attempt - 1)))
wait_time = base_delay * (2 ** (attempt - 1)) async def generate_rag_response(self, query: str, context_str: Optional[str] = None) -> str:
logger.warning(f"⚠️ Ollama attempt {attempt} failed. Retrying in {wait_time}s...") """WP-25: Orchestrierung via DecisionEngine."""
await asyncio.sleep(wait_time) return await self.decision_engine.ask(query)
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 close(self): async def close(self):
"""Schließt die HTTP-Verbindungen."""
if self.ollama_client: if self.ollama_client:
await self.ollama_client.aclose() await self.ollama_client.aclose()
+111 -123
View File
@@ -1,145 +1,133 @@
# config/decision_engine.yaml # config/decision_engine.yaml
# Steuerung der Decision Engine (Intent Recognition & Graph Routing) # VERSION: 3.2.2 (WP-25a: Decoupled MoE Logic)
# VERSION: 2.6.1 (WP-20: Hybrid LLM & WP-22: Semantic Graph Routing)
# STATUS: Active # 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: settings:
llm_fallback_enabled: true llm_fallback_enabled: true
# "auto" nutzt den globalen Default-Provider aus der .env
# Strategie für den Router selbst (Welches Modell erkennt den Intent?)
# "auto" nutzt den in MINDNET_LLM_PROVIDER gesetzten Standard (z.B. openrouter).
router_provider: "auto" 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 # --- EBENE 1: STREAM-LIBRARY (Bausteine basierend auf types.yaml v2.7.0) ---
llm_router_prompt: | streams_library:
Du bist der zentrale Intent-Klassifikator für Mindnet, einen digitalen Zwilling. values_stream:
Analysiere die Nachricht und wähle die passende Strategie. name: "Identität & Ethik"
Antworte NUR mit dem Namen der Strategie. # 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
STRATEGIEN: facts_stream:
- INTERVIEW: User will Wissen erfassen, Notizen anlegen oder Dinge festhalten. name: "Operative Realität"
- DECISION: Rat, Strategie, Abwägung von Werten, "Soll ich tun X?". llm_profile: "synthesis_pro"
- EMPATHY: Gefühle, Reflexion der eigenen Verfassung, Frust, Freude. compression_profile: "compression_fast"
- CODING: Code-Erstellung, Debugging, technische Dokumentation. compression_threshold: 3500
- FACT: Reine Wissensabfrage, Definitionen, Suchen von Informationen. query_template: "Status, Ressourcen und Fakten zu: {query}"
filter_types: ["project", "decision", "task", "goal", "event", "state"]
BEISPIELE: top_k: 5
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:
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
edge_boosts: edge_boosts:
part_of: 2.0 part_of: 2.0
composed_of: 2.0 depends_on: 1.5
similar_to: 1.5 implemented_in: 1.5
caused_by: 0.5
prompt_template: "rag_template"
prepend_instruction: null
# 2. Entscheidungs-Frage (Power-Strategie via Gemini) biography_stream:
DECISION: name: "Persönliche Erfahrung"
description: "Der User sucht Rat, Strategie oder Abwägung." llm_profile: "synthesis_pro"
preferred_provider: "gemini" compression_profile: "compression_fast"
trigger_keywords: compression_threshold: 3000
- "soll ich" query_template: "Welche Erlebnisse habe ich im Kontext von {query} gemacht?"
- "meinung" filter_types: ["experience", "journal", "profile", "person"]
- "besser" top_k: 3
- "empfehlung" edge_boosts:
- "strategie" related_to: 1.5
- "entscheidung" experienced_in: 2.0
- "abwägung"
- "vergleich" risk_stream:
inject_types: ["value", "principle", "goal", "risk"] name: "Risiko-Radar"
# WP-22: Risiken und Konsequenzen im Graphen priorisieren 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: edge_boosts:
blocks: 2.5 blocks: 2.5
solves: 2.0
depends_on: 1.5
risk_of: 2.5
impacts: 2.0 impacts: 2.0
prompt_template: "decision_template" risk_of: 2.5
prepend_instruction: |
!!! ENTSCHEIDUNGS-MODUS (HYBRID AI) !!!
BITTE WÄGE FAKTEN GEGEN FOLGENDE WERTE, PRINZIPIEN UND ZIELE AB:
# 3. Empathie / "Ich"-Modus (Lokal & Privat via Ollama) tech_stream:
EMPATHY: name: "Wissen & Technik"
description: "Reaktion auf emotionale Zustände." llm_profile: "tech_expert"
preferred_provider: "openrouter" compression_profile: "compression_fast"
trigger_keywords: compression_threshold: 4500
- "ich fühle" query_template: "Inhaltliche Details und Definitionen zu: {query}"
- "traurig" filter_types: ["concept", "source", "glossary", "idea", "insight", "skill", "habit"]
- "glücklich" top_k: 5
- "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
edge_boosts: edge_boosts:
uses: 2.5 uses: 2.5
depends_on: 2.0
implemented_in: 3.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: INTERVIEW:
description: "Der User möchte Wissen erfassen." description: "Der User möchte Wissen erfassen (Eingabemodus)."
preferred_provider: "openrouter" llm_profile: "compression_fast"
trigger_keywords: use_streams: []
- "neue notiz"
- "etwas notieren"
- "festhalten"
- "erstellen"
- "dokumentieren"
- "anlegen"
- "interview"
- "erfassen"
- "idee speichern"
- "draft"
inject_types: []
edge_boosts: {}
prompt_template: "interview_template" prompt_template: "interview_template"
prepend_instruction: null
+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
+100 -36
View File
@@ -1,8 +1,9 @@
# config/prompts.yaml — Final V2.6.0 (WP-15b Candidate-Validation) # config/prompts.yaml — VERSION 3.1.2 (WP-25 Cleanup: Multi-Stream Sync)
# WP-20: Optimierte Cloud-Templates zur Unterdrückung von Modell-Geschwätz. # STATUS: Active
# FIX: Explizite Verbote für Einleitungstexte zur Vermeidung von JSON-Parsing-Fehlern. # FIX:
# WP-15b: Integration der binären edge_validation für den Two-Pass Workflow. # - 100% Wiederherstellung der Ingest- & Validierungslogik (Sektion 5-8).
# OLLAMA: UNVERÄNDERT laut Benutzeranweisung. # - Ü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: | system_prompt: |
Du bist 'mindnet', mein digitaler Zwilling und strategischer Partner. Du bist 'mindnet', mein digitaler Zwilling und strategischer Partner.
@@ -17,13 +18,21 @@ system_prompt: |
3. Antworte auf Deutsch (außer bei Code/Fachbegriffen). 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: # Ersetzt das alte 'rag_template'. Nutzt jetzt parallele Streams.
fact_synthesis_v1:
ollama: | ollama: |
QUELLEN (WISSEN): WISSENS-STREAMS:
========================================= =========================================
{context_str} FAKTEN & STATUS:
{facts_stream}
ERFAHRUNG & BIOGRAFIE:
{biography_stream}
WISSEN & TECHNIK:
{tech_stream}
========================================= =========================================
FRAGE: FRAGE:
@@ -31,25 +40,35 @@ rag_template:
ANWEISUNG: 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. Fasse die Informationen zusammen. Sei objektiv und neutral.
gemini: | gemini: |
Kontext meines digitalen Zwillings: {context_str} Beantworte die Wissensabfrage "{query}" basierend auf diesen Streams:
Beantworte strukturiert und präzise: {query} 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: | openrouter: |
Kontext-Analyse für den digitalen Zwilling: Synthese der Wissens-Streams für: {query}
{context_str} Inhalt: {facts_stream} | {biography_stream} | {tech_stream}
Antworte basierend auf dem bereitgestellten Kontext.
Anfrage: {query}
Antworte basierend auf dem Kontext.
# --------------------------------------------------------- # ---------------------------------------------------------
# 2. DECISION: Strategie & Abwägung (Intent: DECISION) # 2. DECISION: Strategie & Abwägung (Intent: DECISION)
# --------------------------------------------------------- # ---------------------------------------------------------
decision_template: # Ersetzt das alte 'decision_template'. Nutzt jetzt parallele Streams.
decision_synthesis_v1:
ollama: | 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: ENTSCHEIDUNGSFRAGE:
@@ -58,7 +77,7 @@ decision_template:
ANWEISUNG: ANWEISUNG:
Du agierst als mein Entscheidungs-Partner. Du agierst als mein Entscheidungs-Partner.
1. Analysiere die Faktenlage aus den Quellen. 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? 3. Wäge ab: Passt die technische/faktische Lösung zu meinen Werten?
FORMAT: FORMAT:
@@ -66,19 +85,26 @@ decision_template:
- **Abgleich:** (Gibt es Konflikte mit Werten/Zielen? Nenne die Quelle!) - **Abgleich:** (Gibt es Konflikte mit Werten/Zielen? Nenne die Quelle!)
- **Empfehlung:** (Klare Meinung: Ja/No/Vielleicht mit Begründung) - **Empfehlung:** (Klare Meinung: Ja/No/Vielleicht mit Begründung)
gemini: | 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: | openrouter: |
Strategische Entscheidungsanalyse: {query} Strategische Multi-Stream Analyse für: {query}
Wertebasis aus dem Graphen: {context_str} 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) # 3. EMPATHY: Der Spiegel / "Ich"-Modus (Intent: EMPATHY)
# --------------------------------------------------------- # ---------------------------------------------------------
empathy_template: empathy_template:
ollama: | ollama: |
KONTEXT (ERFAHRUNGEN & GLAUBENSSÄTZE): KONTEXT (ERFAHRUNGEN & WERTE):
========================================= =========================================
{context_str} ERLEBNISSE & BIOGRAFIE:
{biography_stream}
WERTE & BEDÜRFNISSE:
{values_stream}
========================================= =========================================
SITUATION: SITUATION:
@@ -87,22 +113,26 @@ empathy_template:
ANWEISUNG: ANWEISUNG:
Du agierst jetzt als mein empathischer Spiegel. Du agierst jetzt als mein empathischer Spiegel.
1. Versuche nicht sofort, das Problem technisch zu lösen. 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. 3. Antworte in der "Ich"-Form oder "Wir"-Form. Sei unterstützend.
TONFALL: TONFALL:
Ruhig, verständnisvoll, reflektiert. Keine Aufzählungszeichen, sondern fließender Text. Ruhig, verständnisvoll, reflektiert. Keine Aufzählungszeichen, sondern fließender Text.
gemini: "Sei mein digitaler Spiegel für {query}. 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: {context_str}" openrouter: "Empathische Reflexion der Situation {query}. Persönlicher Kontext: {biography_stream}, {values_stream}"
# --------------------------------------------------------- # ---------------------------------------------------------
# 4. TECHNICAL: Der Coder (Intent: CODING) # 4. TECHNICAL: Der Coder (Intent: CODING)
# --------------------------------------------------------- # ---------------------------------------------------------
technical_template: technical_template:
ollama: | ollama: |
KONTEXT (DOCS & SNIPPETS): KONTEXT (WISSEN & PROJEKTE):
========================================= =========================================
{context_str} TECHNIK & SNIPPETS:
{tech_stream}
PROJEKT-STATUS:
{facts_stream}
========================================= =========================================
TASK: TASK:
@@ -118,11 +148,11 @@ technical_template:
- Kurze Erklärung des Ansatzes. - Kurze Erklärung des Ansatzes.
- Markdown Code-Block (Copy-Paste fertig). - Markdown Code-Block (Copy-Paste fertig).
- Wichtige Edge-Cases. - Wichtige Edge-Cases.
gemini: "Generiere Code für {query} unter Berücksichtigung von {context_str}." gemini: "Generiere Code für {query} unter Berücksichtigung von {tech_stream} und {facts_stream}."
openrouter: "Technischer Support für {query}. Code-Referenzen: {context_str}" openrouter: "Technischer Support für {query}. Referenzen: {tech_stream}, Projekt-Kontext: {facts_stream}"
# --------------------------------------------------------- # ---------------------------------------------------------
# 5. INTERVIEW: Der "One-Shot Extractor" (Performance Mode) # 5. INTERVIEW: Der "One-Shot Extractor" (WP-07)
# --------------------------------------------------------- # ---------------------------------------------------------
interview_template: interview_template:
ollama: | ollama: |
@@ -160,7 +190,7 @@ interview_template:
openrouter: "Strukturiere den Input {query} nach dem Schema {schema_fields} für Typ {target_type}." openrouter: "Strukturiere den Input {query} nach dem Schema {schema_fields} für Typ {target_type}."
# --------------------------------------------------------- # ---------------------------------------------------------
# 6. EDGE_ALLOCATION: Kantenfilter (Intent: OFFLINE_FILTER) # 6. EDGE_ALLOCATION: Kantenfilter (Ingest)
# --------------------------------------------------------- # ---------------------------------------------------------
edge_allocation_template: edge_allocation_template:
ollama: | ollama: |
@@ -200,7 +230,7 @@ edge_allocation_template:
OUTPUT: OUTPUT:
# --------------------------------------------------------- # ---------------------------------------------------------
# 7. SMART EDGE ALLOCATION: Extraktion (Intent: INGEST) # 7. SMART EDGE ALLOCATION: Extraktion (Ingest)
# --------------------------------------------------------- # ---------------------------------------------------------
edge_extraction: edge_extraction:
ollama: | ollama: |
@@ -240,7 +270,7 @@ edge_extraction:
OUTPUT: OUTPUT:
# --------------------------------------------------------- # ---------------------------------------------------------
# 8. WP-15b: EDGE VALIDATION (Intent: VALIDATE) # 8. WP-15b: EDGE VALIDATION (Ingest/Validate)
# --------------------------------------------------------- # ---------------------------------------------------------
edge_validation: edge_validation:
gemini: | gemini: |
@@ -271,3 +301,37 @@ edge_validation:
ZIEL: {target_title} ({target_summary}) ZIEL: {target_title} ({target_summary})
BEZIEHUNG: {edge_kind} BEZIEHUNG: {edge_kind}
Ist diese Verbindung valide? Antworte NUR mit YES oder NO. 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:
+2 -2
View File
@@ -151,8 +151,8 @@ Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten
## 6. Dokumentations-Status ## 6. Dokumentations-Status
**Aktuelle Version:** 2.9.1 **Aktuelle Version:** 2.9.3
**Letzte Aktualisierung:** 2025-01-XX **Letzte Aktualisierung:** 2025-12-31
**Status:** ✅ Vollständig und aktiv gepflegt **Status:** ✅ Vollständig und aktiv gepflegt
**Hinweis:** Diese Dokumentation wird kontinuierlich aktualisiert. Bei Fragen oder Verbesserungsvorschlägen bitte im Repository melden. **Hinweis:** Diese Dokumentation wird kontinuierlich aktualisiert. Bei Fragen oder Verbesserungsvorschlägen bitte im Repository melden.
+16 -4
View File
@@ -2,8 +2,8 @@
doc_type: glossary doc_type: glossary
audience: all audience: all
status: active status: active
version: 2.8.1 version: 3.0.0
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." context: "Zentrales Glossar für Mindnet v3.0.0. 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) und Mistral-safe Parsing."
--- ---
# Mindnet Glossar # 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. * **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). * **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). * **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`). * **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. * **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. * **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. * **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. * **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. * **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. * **Database Package (WP-14):** Zentralisiertes Infrastruktur-Paket (`app.core.database`), das den Qdrant-Client (`qdrant.py`) und das Point-Mapping (`qdrant_points.py`) verwaltet.
@@ -48,3 +52,11 @@ context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-C
* **Pass 1 (Pre-Scan):** Schnelles Scannen aller Dateien zur Befüllung des LocalBatchCache. * **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. * **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.
+43 -11
View File
@@ -3,8 +3,8 @@ doc_type: user_manual
audience: user, mindmaster audience: user, mindmaster
scope: chat, ui, feedback, graph scope: chat, ui, feedback, graph
status: active status: active
version: 2.6 version: 2.9.3
context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas und des Graph Explorers." context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas, Multi-Stream RAG und des Graph Explorers."
--- ---
# Chat & Graph Usage Guide # Chat & Graph Usage Guide
@@ -60,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) ### 3.1 Intent-Erkennung (Hybrid-Router)
Ausgelöst durch `?` oder W-Wörter.
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**. * **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'." * *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**. * **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..." * *Beispiel:* "Ich bin frustriert." -> "Das erinnert mich an Projekt Y, da ging es uns ähnlich..."
* **Fakten ("Was ist?"):** Der **Bibliothekar**. * **Fakten ("Was ist?", "Wann..."):** Der **Bibliothekar**.
* Liefert präzise Definitionen. * Nutzt: Facts Stream, Tech Stream, Biography Stream
* Liefert präzise Definitionen und zeitliche Informationen
### 3.2 Befehls-Modus (Interview) ### 3.2 Befehls-Modus (Interview)
Ausgelöst durch Aussagen wie "Neues Projekt", "Ich will festhalten". Ausgelöst durch Aussagen wie "Neues Projekt", "Ich will festhalten".
@@ -84,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. Mindnet liefert eine **Begründung** ("Reasons"), warum es etwas gefunden hat.
Öffne eine Quellen-Karte, um zu sehen: Öffne eine Quellen-Karte, um zu sehen:
* *"Hohe textuelle Übereinstimmung."* (Semantik) * *"Hohe textuelle Übereinstimmung."* (Semantik)
* *"Bevorzugt aufgrund des Typs 'decision'."* (Wichtigkeit) * *"Bevorzugt aufgrund des Typs 'decision'."* (Wichtigkeit)
* *"Verweist auf 'Projekt X' via 'depends_on'."* (Graph-Kontext) * *"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.
--- ---
+13 -1
View File
@@ -3,7 +3,7 @@ doc_type: user_manual
audience: user, author audience: user, author
scope: vault, markdown, schema scope: vault, markdown, schema
status: active 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." 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]]." > "Daher [[rel:depends_on Qdrant]]."
> "Dieses Konzept ist [[rel:similar_to Pinecone]]." > "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:** **Gültige Relationen:**
* `depends_on`: Hängt ab von / Benötigt. * `depends_on`: Hängt ab von / Benötigt.
* `blocks`: Blockiert oder gefährdet (z.B. Risiko -> Projekt). * `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]] > [[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!] ### 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. 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 doc_type: concept
audience: architect, product_owner audience: architect, product_owner
scope: ai, router, personas, resilience scope: ai, router, personas, resilience, agentic_rag, moe
status: active status: active
version: 2.8.1 version: 3.0.0
context: "Fachkonzept der hybriden KI-Persönlichkeit, der Provider-Kaskade und der kognitiven Resilienz (Deep Fallback)." context: "Fachkonzept der hybriden KI-Persönlichkeit, Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE), Provider-Kaskade und kognitiven Resilienz (Deep Fallback)."
--- ---
# Konzept: KI-Persönlichkeit & Router # 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. 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-basiertes Routing (WP-25)
* **Intent:** Der Nutzer hat eine Frage oder ein Problem (`FACT`, `DECISION`, `EMPATHY`).
* **Aktion:** Das System sucht im Gedächtnis und generiert eine Antwort. 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) ### Modus B: Interview (Knowledge Capture)
* **Intent:** Der Nutzer will Wissen speichern (`INTERVIEW`). * **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. 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. * **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. Mindnet wechselt den Hut, je nach Situation.
### 3.1 Der Berater (Strategy: DECISION) ### 3.1 Der Berater (Strategy: DECISION)
* **Auslöser:** Fragen wie „Soll ich...?“, „Was ist besser?“. * **Auslöser:** Fragen wie „Soll ich...?", „Was ist besser?", „Empfehlung...".
* **Strategic Retrieval:** Lädt aktiv Notizen der Typen `value` (Werte), `goal` (Ziele) und `risk` (Risiken), auch wenn sie im Text nicht direkt vorkommen. * **Multi-Stream Retrieval (WP-25):** Führt parallele Abfragen in Values Stream, Facts Stream und Risk Stream aus.
* **Reasoning:** *„Wäge die Fakten gegen meine Werte ab. Sei strikt bei Risiken.“* * **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) ### 3.2 Der Spiegel (Strategy: EMPATHY)
* **Auslöser:** Emotionale Aussagen („Ich bin frustriert“). * **Auslöser:** Emotionale Aussagen („Ich bin frustriert", „Ich fühle...", „Stress...").
* **Strategic Retrieval:** Lädt `experience` (Erfahrungen) und `belief` (Glaubenssätze). * **Multi-Stream Retrieval (WP-25):** Führt parallele Abfragen in Biography Stream und Values Stream aus.
* **Reasoning:** *„Nutze meine eigenen Erfahrungen, um die Situation einzuordnen.“* * **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) ### 3.3 Der Bibliothekar (Strategy: FACT_WHAT / FACT_WHEN)
* **Auslöser:** Sachfragen („Was ist Qdrant?“). * **Auslöser:** Sachfragen („Was ist...?", „Welche sind...?", „Wann...?", „Datum...").
* **Behavior:** Präzise, neutral, kurz. * **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.
--- ---
+44 -5
View File
@@ -3,8 +3,8 @@ doc_type: concept
audience: architect, product_owner audience: architect, product_owner
scope: graph, logic, provenance scope: graph, logic, provenance
status: active status: active
version: 2.7.0 version: 2.9.1
context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik und WP-22 Scoring-Prinzipien." context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik, WP-15c Multigraph-Support und WP-22 Scoring-Prinzipien."
--- ---
# Konzept: Die Graph-Logik # Konzept: Die Graph-Logik
@@ -59,7 +59,7 @@ Um eine konsistente mathematische Gewichtung zu garantieren, werden alle Kanten
### 2.2 Provenance (Herkunft & Vertrauen) ### 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)** **1. Explicit (Der Mensch hat es gesagt)**
* *Quelle:* Inline-Links (`[[rel:...]]`) oder Wikilinks im Text. * *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)**. * *Vertrauen:* **Niedrig (0.7)**.
* *Bedeutung:* Systemseitige Heuristik. Diese Verbindungen dienen der Entdeckung neuer Pfade, haben aber weniger Gewicht als explizite Links. * *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) ## 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. Das System garantiert fachliche Konsistenz auch bei mehrfachen Importen.
* **Stabile IDs:** Deterministische IDs verhindern Duplikate bei Re-Imports. * **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.
@@ -1,10 +1,10 @@
--- ---
doc_type: technical_reference doc_type: technical_reference
audience: developer, integrator audience: developer, integrator
scope: api, endpoints, integration scope: api, endpoints, integration, agentic_rag
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Vollständige API-Referenz für alle Mindnet-Endpunkte. Basis für Integration und Entwicklung." 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 # API Reference
@@ -96,21 +96,37 @@ Hauptendpunkt für RAG-Chat und Interview-Modus. Unterstützt Streaming.
**Response (Non-Streaming):** **Response (Non-Streaming):**
```json ```json
{ {
"intent": "FACT", "query_id": "uuid",
"response": "Mindnet ist ein persönliches KI-Gedächtnis...", "answer": "Mindnet ist ein persönliches KI-Gedächtnis...",
"sources": [...], "sources": [
"query_id": "uuid" {
"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):** **Response (Streaming):**
Server-Sent Events (SSE) mit Chunks der Antwort. Server-Sent Events (SSE) mit Chunks der Antwort.
**Intent-Typen:** **Intent-Typen (WP-25):**
- `FACT`: Wissensabfrage - `FACT_WHAT`: Wissensabfrage (Wissen/Listen)
- `DECISION`: Entscheidungsfrage - `FACT_WHEN`: Zeitpunkte (Termine, Daten)
- `EMPATHY`: Emotionale Anfrage - `DECISION`: Entscheidungsfrage (Beratung, Strategie)
- `INTERVIEW`: Wissen erfassen - `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").
--- ---
@@ -144,8 +160,11 @@ Lädt den Subgraphen um eine Note herum.
"kind": "depends_on", "kind": "depends_on",
"source": "uuid", "source": "uuid",
"target": "uuid", "target": "uuid",
"target_section": "P3 – Disziplin", // Optional: Abschnitts-Name bei Deep-Links
"weight": 1.4, "weight": 1.4,
"direction": "out" "direction": "out",
"provenance": "explicit",
"confidence": 1.0
} }
], ],
"stats": { "stats": {
@@ -1,32 +1,58 @@
--- ---
doc_type: technical_reference doc_type: technical_reference
audience: developer, architect audience: developer, architect
scope: backend, chat, llm_service, traffic_control, resilience scope: backend, chat, llm_service, traffic_control, resilience, agentic_rag, moe
status: active status: active
version: 2.9.1 version: 3.0.0
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.3.6) und der WP-20 Resilienz-Logik." context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.5.2), WP-25 Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE) 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)
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):** 1. **Keyword Fast-Path (Sofortige Erkennung):**
* Prüfung auf Vorhandensein von `?` oder W-Wörtern (Wer, Wie, Was, Soll ich). * Prüft `trigger_keywords` aus `decision_engine.yaml` (z.B. "Soll ich", "Wann", "Was ist").
* Wenn positiv: **RAG Modus** (Interview wird blockiert). * Wenn Match: Sofortige Intent-Zuordnung ohne LLM-Call.
2. **Keyword Scan (Fast Path):** * **Strategien:** FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW.
* Lädt `types.yaml` (Objekte) und `decision_engine.yaml` (Handlungen). 2. **Type Keywords (Interview-Modus):**
* Wenn Match (z.B. "Projekt" + "neu"): **INTERVIEW Modus**. * Lädt `types.yaml` und prüft `detection_keywords` für Objekt-Erkennung.
3. **LLM Fallback (Slow Path):** * Wenn Match und keine Frage: **INTERVIEW Modus** (Datenerfassung).
* Wenn unklar: Anfrage an LLM zur Klassifizierung mittels `router_prompt`. 3. **LLM Slow-Path (Semantische Analyse):**
* Wenn unklar: Anfrage an `DecisionEngine._determine_strategy()` zur LLM-basierten Klassifizierung.
* Nutzt `intent_router_v1` Prompt aus `prompts.yaml`.
### 1.2 Prompt-Auflösung (Bulletproof Resolution) ### 1.2 Mixture of Experts (MoE) Architektur (WP-25a)
Seit WP-25a nutzt MindNet eine **profilbasierte Experten-Steuerung** statt einer globalen Provider-Konfiguration. Jede Systemaufgabe wird einem dedizierten Profil zugewiesen:
**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
**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
**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 Prompt-Auflösung (Bulletproof Resolution)
Um Kompatibilitätsprobleme mit verschachtelten YAML-Prompts zu vermeiden, nutzt der Router die Methode `llm.get_prompt()`. Diese implementiert eine **Provider-Kaskade**: 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`). * **Spezifischer Provider:** Das System sucht zuerst nach einem Prompt für den aktiv konfigurierten Provider (z.B. `openrouter`).
@@ -34,24 +60,94 @@ Um Kompatibilitätsprobleme mit verschachtelten YAML-Prompts zu vermeiden, nutzt
* **Basis-Fallback:** Als letzte Instanz wird das `ollama`-Template geladen. * **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. * **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.3 RAG Flow (Technisch) ### 1.4 Multi-Stream Retrieval (WP-25)
Wenn der Intent `FACT` oder `DECISION` ist, wird folgender Flow ausgeführt: Anstelle einer einzelnen Suche führt die `DecisionEngine` nun **parallele Abfragen** in spezialisierten Streams aus:
1. **Pre-Processing:** Query Rewriting (optional). **Stream-Library (definiert in `decision_engine.yaml`):**
2. **Context Enrichment:** * **Values Stream:** Extrahiert Identität, Ethik und Prinzipien (`value`, `principle`, `belief`, etc.).
* Abruf via `retriever.py` (Hybrid Search). * **Facts Stream:** Liefert operative Daten zu Projekten, Tasks und Status (`project`, `decision`, `task`, etc.).
* Integration von **Edge Boosts** aus der `decision_engine.yaml` zur Beeinflussung der Graph-Gewichtung. * **Biography Stream:** Greift auf persönliche Erfahrungen und Journal-Einträge zu (`experience`, `journal`, `profile`).
* Injection von Metadaten (`[TYPE]`, `[SCORE]`) in den Prompt. * **Risk Stream:** Identifiziert Hindernisse und potenzielle Gefahren (`risk`, `obstacle`, `bias`).
3. **Prompt Construction:** Assembly aus System-Prompt (Persona) + Context + Query. * **Tech Stream:** Bündelt technisches Wissen, Code und Dokumentation (`concept`, `source`, `glossary`, etc.).
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. **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: Mit Version 2.8.1 wurde die Architektur der Antwort-Generierung grundlegend gehärtet:
@@ -107,10 +203,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`. 1. **Query ID:** Generiert bei jedem `/chat` Call eine `UUIDv4`.
2. **Logging:** Speichert einen Snapshot in `data/logs/query_snapshot.jsonl` (Input + Retrieved Context). 2. **Stream-Tracing:** Jeder Treffer enthält `stream_origin` für Zuordnung zum Quell-Stream.
3. **Feedback:** Der `/feedback` Endpoint verknüpft das User-Rating (1-5) mit der `query_id`. 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 doc_type: technical_reference
audience: developer, admin audience: developer, admin
scope: configuration, env, registry, scoring, resilience, modularization scope: configuration, env, registry, scoring, resilience, modularization, agentic_rag, moe
status: active status: active
version: 2.9.1 version: 3.0.0
context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen und die Edge Registry Struktur unter Berücksichtigung von WP-14." context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen, Edge Registry Struktur, WP-25 Multi-Stream RAG und WP-25a Mixture of Experts (MoE) unter Berücksichtigung von WP-14."
--- ---
# Konfigurations-Referenz # Konfigurations-Referenz
@@ -224,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 ### 5.1 Intent Recognition: Hybrid-Routing (WP-25)
Das System nutzt ein zweistufiges Verfahren, um die Absicht des Nutzers zu identifizieren: 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. 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. **Slow Path (LLM Router):** Wenn kein Keyword matcht und `llm_fallback_enabled: true` gesetzt ist, analysiert ein LLM die Nachricht mittels Few-Shot Prompting. 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 #### 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. Der Router nutzt den `llm_router_prompt`, um Anfragen in eine der fünf Kern-Strategien (`FACT`, `DECISION`, `EMPATHY`, `CODING`, `INTERVIEW`) zu klassifizieren.
@@ -244,36 +245,164 @@ Der Router nutzt den `llm_router_prompt`, um Anfragen in eine der fünf Kern-Str
--- ---
### 5.2 Strategie-Mechaniken (Graph Shaping) ### 5.2 Multi-Stream Konfiguration (WP-25)
Jede Strategie definiert drei Hebel, um das Ergebnis des Retrievers zu beeinflussen:
* **`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". * **`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"). * **`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)* | | **FACT_WHAT** | Wissensabfrage & Listen | `facts_stream`, `tech_stream`, `biography_stream` | `part_of` (2.0), `depends_on` (1.5), `implemented_in` (1.5) |
| **DECISION** | Rat, Strategie & Abwägung | `blocks` (2.5), `solves` (2.0), `risk_of` (2.5) | `value`, `principle`, `goal`, `risk` | | **FACT_WHEN** | Zeitpunkte & Termine | `facts_stream`, `biography_stream`, `tech_stream` | `part_of` (2.0), `depends_on` (1.5) |
| **EMPATHY** | Emotionale Resonanz | `based_on` (2.0), `experienced_in` (2.5), `related_to` (2.0) | `experience`, `belief`, `profile` | | **DECISION** | Rat, Strategie & Abwägung | `values_stream`, `facts_stream`, `risk_stream` | `blocks` (2.5), `impacts` (2.0), `risk_of` (2.5) |
| **CODING** | Programmierung & Syntax | `implemented_in` (3.0), `uses` (2.5), `depends_on` (2.0) | `snippet`, `reference`, `source` | | **EMPATHY** | Emotionale Resonanz | `biography_stream`, `values_stream` | `related_to` (1.5), `experienced_in` (2.0) |
| **INTERVIEW** | Erfassung neuer Daten | *(Keine)* | *(Keine)* | | **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. 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. * **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. * **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. > **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.1.2)
Seit WP-25 nutzen die Synthese-Templates explizite Stream-Variablen:
**Template-Struktur:**
```yaml
decision_synthesis_v1:
ollama: |
WERTE & PRINZIPIEN (Identität):
{values_stream}
OPERATIVE FAKTEN (Realität):
{facts_stream}
RISIKO-RADAR (Konsequenzen):
{risk_stream}
ENTSCHEIDUNGSFRAGE:
{query}
```
**Pre-Initialization:**
Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors bei unvollständigen Konfigurationen).
**Provider-spezifische Templates:**
Separate Versionen für Ollama, Gemini und OpenRouter.
---
## 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.
---
Auszug aus der decision_engine.yaml Auszug aus der decision_engine.yaml
```yaml ```yaml
@@ -3,7 +3,7 @@ doc_type: technical_reference
audience: developer, architect audience: developer, architect
scope: database, qdrant, schema scope: database, qdrant, schema
status: active 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." 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`) ## 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-Schema:**
```json ```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) "source_id": "string (keyword)", // Chunk-ID (Start)
"target_id": "string (keyword)", // Chunk-ID oder Note-Titel (bei Unresolved) "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') "kind": "string (keyword)", // Beziehungsart (z.B. 'depends_on')
"scope": "string (keyword)", // Immer 'chunk' (Legacy-Support: 'note') "scope": "string (keyword)", // Immer 'chunk' (Legacy-Support: 'note')
"note_id": "string (keyword)", // Owner Note ID (Ursprung der Kante) "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:** **Erforderliche Indizes:**
Es müssen Payload-Indizes für folgende Felder existieren: Es müssen Payload-Indizes für folgende Felder existieren:
* `source_id` * `source_id`
* `target_id` * `target_id`
* `target_section` (neu: Keyword-Index für Section-basierte Filterung)
* `kind` * `kind`
* `scope` * `scope`
* `note_id` * `note_id`
@@ -3,7 +3,7 @@ doc_type: technical_reference
audience: developer, frontend_architect audience: developer, frontend_architect
scope: architecture, graph_viz, state_management scope: architecture, graph_viz, state_management
status: active status: active
version: 2.7.0 version: 2.9.1
context: "Technische Dokumentation des modularen Streamlit-Frontends, der Graph-Engines und des Editors." context: "Technische Dokumentation des modularen Streamlit-Frontends, der Graph-Engines und des Editors."
--- ---
@@ -1,10 +1,10 @@
--- ---
doc_type: technical_reference doc_type: technical_reference
audience: developer, devops audience: developer, devops
scope: backend, ingestion, smart_edges, edge_registry, modularization scope: backend, ingestion, smart_edges, edge_registry, modularization, moe
status: active status: active
version: 2.9.0 version: 2.14.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." context: "Detaillierte technische Beschreibung der Import-Pipeline, Two-Pass-Workflow (WP-15b), modularer Datenbank-Architektur (WP-14) und WP-25a profilgesteuerte Validierung. Integriert Mistral-safe Parsing und Deep Fallback."
--- ---
# Ingestion Pipeline & Smart Processing # 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):** 4. **Edge Registry Initialisierung (WP-22):**
* Laden der Singleton-Instanz der `EdgeRegistry`. * Laden der Singleton-Instanz der `EdgeRegistry`.
* Validierung der Vokabular-Datei unter `MINDNET_VOCAB_PATH`. * 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`. * Bestimmung von `chunking_profile` und `retriever_weight` via zentraler `TypeRegistry`.
* **Priorität:** 1. Frontmatter (Override) -> 2. `types.yaml` (Type) -> 3. Global Default. * **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):** 6. **LocalBatchCache & Summary Generation (WP-15b):**
* Erstellung von Kurz-Zusammenfassungen für jede Note. * Erstellung von Kurz-Zusammenfassungen für jede Note.
* Speicherung im `batch_cache` als Referenzrahmen für die spätere Kantenvalidierung. * Speicherung im `batch_cache` als Referenzrahmen für die spätere Kantenvalidierung.
@@ -49,9 +50,11 @@ 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. * 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. * Die Namensauflösung erfolgt nun über das modularisierte `database`-Paket.
10. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3). 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):**
* Der `SemanticAnalyzer` schlägt Kanten-Kandidaten vor. * 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):** 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).
* **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]). * **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. * **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. 12. **Inline-Kanten finden:** Parsing von `[[rel:...]]` und Callouts.
@@ -59,7 +62,9 @@ Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durc
* Jede Kante wird via `EdgeRegistry` normalisiert (z.B. `basiert_auf` -> `based_on`). * Jede Kante wird via `EdgeRegistry` normalisiert (z.B. `basiert_auf` -> `based_on`).
* Unbekannte Typen werden in `unknown_edges.jsonl` protokolliert. * Unbekannte Typen werden in `unknown_edges.jsonl` protokolliert.
14. **Default- & Strukturkanten:** Anwendung der `edge_defaults` und Erzeugung von Systemkanten (`belongs_to`, `next`, `prev`). 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. 16. **Database Sync (WP-14):** Batch-Upsert aller Points in die Collections `{prefix}_chunks` und `{prefix}_edges` über die zentrale Infrastruktur.
--- ---
@@ -126,19 +131,44 @@ Das Chunking ist profilbasiert und bezieht seine Konfiguration dynamisch aus der
| `sliding_smart_edges`| `sliding_window` | Max: 600, Target: 400 | Fließtexte (Projekte). | | `sliding_smart_edges`| `sliding_window` | Max: 600, Target: 400 | Fließtexte (Projekte). |
| `structured_smart_edges` | `by_heading` | `strict: false` | Strukturierte Texte. | | `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). **Kernprinzipien:**
* **Modus "Strict" (`strict_heading_split: true`):** * **Atomic Section Logic:** Überschriften und deren Inhalte werden als atomare Einheiten behandelt und nicht über Chunk-Grenzen hinweg getrennt.
* Jede Überschrift (`<= split_level`) erzwingt einen neuen Chunk. * **H1-Context Preservation:** Der Dokumenttitel (H1) wird zuverlässig als Breadcrumb in das Embedding-Fenster (`window`) aller Chunks injiziert.
* *Merge-Check:* Wenn der vorherige Chunk leer war (nur Überschriften), wird gemergt. * **Signature Alignment:** Parameter-Synchronisierung zwischen Orchestrator und Strategien (`context_prefix` statt `doc_title`).
* *Safety Net:* Wird ein Abschnitt zu lang (> `max` Token), wird auch ohne Überschrift getrennt.
* **Modus "Soft" (`strict_heading_split: false`):** **Split Level:** Definiert die Tiefe (z.B. `2` = H1 & H2 triggern Split).
* **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. **Modus "Strict" (`strict_heading_split: true`):**
* *Safety Net:* Auch hier greift das `max` Token Limit. * 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.
--- ---
@@ -163,4 +193,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. **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. 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 audience: developer, data_scientist
scope: backend, retrieval, scoring, modularization scope: backend, retrieval, scoring, modularization
status: active status: active
version: 2.9.0 version: 2.9.1
context: "Detaillierte Dokumentation der Scoring-Algorithmen, inklusive WP-22 Lifecycle-Modifier, Intent-Boosting und WP-14 Modularisierung." context: "Detaillierte Dokumentation der Scoring-Algorithmen, inklusive WP-22 Lifecycle-Modifier, Intent-Boosting, WP-15c Diversity Engine und WP-14 Modularisierung."
--- ---
# Retrieval & Scoring Algorithmen # 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). 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) ### Die Komponenten (Klassisch v2.4)
**1. Semantic Score ($S_{sem}$):** **1. Semantic Score ($S_{sem}$):**
@@ -43,13 +50,15 @@ $$
### Die WP-22 Erweiterungen (v2.7.0) ### 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`). * **Herkunft:** Feld `status` aus dem Frontmatter (verarbeitet in `retriever_scoring.get_status_multiplier`).
* **Zweck:** Bestraft unfertiges Wissen (Drafts) oder bevorzugt stabiles Wissen. * **Zweck:** Wirkt als **Multiplikator** auf die Basis-Semantik. Bestraft unfertiges Wissen (Drafts) oder bevorzugt stabiles Wissen.
* **Werte (Auftrag WP-22):** * `stable`: **1.2** (Belohnung für verifiziertes Wissen). * **Werte (WP-15c):**
* `active`: **1.0** (Standard-Gewichtung). * `stable`: **1.2** (Belohnung für verifiziertes Wissen)
* `draft`: **0.5** (Malus für unfertige Fragmente). * `active`: **1.0** (Standard-Gewichtung)
* `system`: Exkludiert (siehe Ingestion Lifecycle Filter). * `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}$):** **6. Intent Boost ($B_{intent}$):**
* **Herkunft:** Dynamische Injektion durch die Decision Engine basierend auf der Nutzerfrage. * **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. * 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. * 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`). * 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. * 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. * 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:** **Erweiterte JSON-Struktur:**
+19 -4
View File
@@ -1,10 +1,10 @@
--- ---
doc_type: operations_manual doc_type: operations_manual
audience: admin, devops audience: admin, devops
scope: deployment, maintenance, backup, edge_registry scope: deployment, maintenance, backup, edge_registry, moe
status: active status: active
version: 2.7.0 version: 3.0.0
context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v2.7." context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v3.0.0 inklusive WP-25a Mixture of Experts (MoE) Konfiguration."
--- ---
# Admin Operations Guide # 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). 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) ### 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 ```bash
# Modelle laden # Modelle laden
@@ -57,6 +57,14 @@ ollama pull nomic-embed-text
curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}' 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) ## 2. Deployment (Systemd Services)
@@ -280,3 +288,10 @@ python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
# 2. Neu importieren (Force Hash recalculation) # 2. Neu importieren (Force Hash recalculation)
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force 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.
+19 -7
View File
@@ -1,10 +1,10 @@
--- ---
doc_type: developer_guide doc_type: developer_guide
audience: developer audience: developer
scope: workflow, testing, architecture, modules, modularization scope: workflow, testing, architecture, modules, modularization, agentic_rag
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), Modul-Interna, Setup und Git-Workflow." context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), WP-25 Agentic Multi-Stream RAG, Modul-Interna, Setup und Git-Workflow."
--- ---
# Mindnet Developer Guide & Workflow # Mindnet Developer Guide & Workflow
@@ -236,7 +236,7 @@ Das Backend ist das Herzstück. Es stellt die Logik via REST-API bereit.
| :--- | :--- | :--- | :--- | | :--- | :--- | :--- | :--- |
| **Entry** | `app/main.py` | 🟢 **Core** | **Entrypoint.** Initialisiert FastAPI, CORS, und bindet alle Router ein. | | **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. | | **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/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/query.py` | 🟢 **API** | **Search API.** Klassischer Hybrid-Retriever Endpunkt. |
| | `app/routers/graph.py` | 🟢 **API** | **Viz API.** Liefert Knoten/Kanten für Frontend-Graphen (Cytoscape). | | | `app/routers/graph.py` | 🟢 **API** | **Viz API.** Liefert Knoten/Kanten für Frontend-Graphen (Cytoscape). |
@@ -393,12 +393,24 @@ Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration*
edge_defaults: ["blocks"] # Automatische Kante edge_defaults: ["blocks"] # Automatische Kante
detection_keywords: ["gefahr", "risiko"] detection_keywords: ["gefahr", "risiko"]
``` ```
2. **Strategie (`config/decision_engine.yaml`):** 2. **Strategie (`config/decision_engine.yaml` v3.2.2, WP-25/25a):**
```yaml ```yaml
DECISION: 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: "gemini-1.5-mistralai/mistral-7b-instruct: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.
### Workflow B: Graph-Farben ändern ### Workflow B: Graph-Farben ändern
1. Öffne `app/frontend/ui_config.py`. 1. Öffne `app/frontend/ui_config.py`.
+19 -9
View File
@@ -3,8 +3,8 @@ doc_type: developer_guide
audience: developer, tester audience: developer, tester
scope: testing, quality_assurance, test_strategies scope: testing, quality_assurance, test_strategies
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Umfassender Test-Guide für Mindnet: Test-Strategien, Test-Frameworks, Test-Daten und Best Practices." context: "Umfassender Test-Guide für Mindnet: Test-Strategien, Test-Frameworks, Test-Daten und Best Practices inklusive WP-25 Multi-Stream RAG."
--- ---
# Testing Guide # Testing Guide
@@ -245,19 +245,29 @@ class TestIngest(unittest.IsolatedAsyncioTestCase):
- `tests/test_edges_defaults_smoke.py` - `tests/test_edges_defaults_smoke.py`
- `scripts/edges_full_check.py` - `scripts/edges_full_check.py`
### 4.4 Chat & Intent-Tests ### 4.4 Chat & Intent-Tests (WP-25)
**Was wird getestet:** **Was wird getestet:**
- Intent-Erkennung (FACT, DECISION, EMPATHY, INTERVIEW) - Intent-Erkennung (FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW)
- Decision Engine - 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 - Interview-Modus
- Feedback-Loop - Feedback-Loop
**Tests:** **Tests:**
- `tests/test_wp06_decision.py` - `tests/test_wp06_decision.py` - Decision Engine (Legacy)
- `tests/test_interview_intent.py` - `tests/test_interview_intent.py` - Interview-Modus
- `tests/test_chat_wp05.py` - `tests/test_chat_wp05.py` - Chat-Backend (Legacy)
- `tests/test_feedback_smoke.py` - `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 ### 4.5 Ingestion-Tests
+42 -43
View File
@@ -2,14 +2,14 @@
doc_type: roadmap doc_type: roadmap
audience: product_owner, developer audience: product_owner, developer
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b." context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b/15c/25."
--- ---
# Mindnet Active Roadmap # Mindnet Active Roadmap
**Aktueller Stand:** v2.9.1 (Post-WP14 / WP-15b) **Aktueller Stand:** v2.9.3 (Post-WP25: Agentic Multi-Stream RAG)
**Fokus:** Modularisierung, Two-Pass Ingestion & Graph Intelligence. **Fokus:** Agentic Orchestration, Multi-Stream Retrieval & Wissens-Synthese.
| Phase | Fokus | Status | | Phase | Fokus | Status |
| :--- | :--- | :--- | | :--- | :--- | :--- |
@@ -48,6 +48,8 @@ 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-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-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-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. |
### 2.1 WP-22 Lessons Learned ### 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. * **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 +193,50 @@ 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. 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`. 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 ### WP-25a: Mixture of Experts (MoE) & Fallback-Kaskade
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. **Status:** ✅ Fertig (v3.0.0)
#### 2. Funktionsbeschreibung: Die Streams **Ergebnis:** Transformation 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.
Die Daten aus der `types.yaml` werden in drei logische Verarbeitungseinheiten unterteilt:
##### A. Identity Stream (Die Wahrheitsebene) **Kern-Features:**
* **Inhalt:** `value`, `belief`, `trait`, `principle`, `need`, `boundary`, `bias`. 1. **Intent-basiertes Routing:** Hybrid-Modus mit Keyword Fast-Path und LLM Slow-Path
* **Zweck:** Definition des moralischen Kompasses, der psychologischen Grundbedürfnisse und kognitiven Muster. 2. **Multi-Stream Retrieval:** Parallele Abfragen in spezialisierten Streams (Values, Facts, Biography, Risk, Tech)
* **Wirkung:** Liefert das "Warum" hinter jeder Handlung. 3. **Stream-Tracing:** Jeder Treffer wird mit `stream_origin` markiert
4. **Wissens-Synthese:** Template-basierte Zusammenführung mit expliziten Stream-Variablen
5. **Fehler-Resilienz:** Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage
##### B. History Stream (Die Evidenzebene) **Technische Details:**
* **Inhalt:** `experience`, `event`, `source`, `journal`, `person`. - Decision Engine v1.0.3: Multi-Stream Orchestrator
* **Zweck:** Bereitstellung empirischer Belege aus der Vergangenheit und sozialer Kontexte. - Chat Router v3.0.2: Hybrid Router Integration
* **Wirkung:** Verankert die Antwort in real erlebten Mustern und Fakten. - LLM Service v3.4.2: Ingest-Stability Patch
- decision_engine.yaml v3.1.6: Multi-Stream Konfiguration
- prompts.yaml v3.1.2: Stream-Templates
##### C. Action Stream (Die Dynamikebene) **Ergebnis (WP-25a):** 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.
* **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.
**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
#### 3. Technische Wirkungsweise (Solution Sketch) **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
##### Schritt 1: Query-Decomposition **Ausblick (WP-25b):**
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). - Prompt-Orchestration & Model-Specific Tuning
- Kontext-Budgeting: Intelligente Token-Verteilung
##### Schritt 2: Parallel Stream Retrieval - Stream-specific Provider: Unterschiedliche KI-Modelle pro Wissensbereich
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.
--- ---
### WP-24 – Proactive Discovery & Agentic Knowledge Mining ### WP-24 – Proactive Discovery & Agentic Knowledge Mining
+85 -9
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." * 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! Damit hast du das perfekte Paket für den nächsten Entwicklungsschritt geschnürt!
```
---
## WP-22: Content Lifecycle & Meta-Config ## 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:** **Dein Auftrag:**
Implementiere (A) den Content-Lifecycle, (B) die Edge-Registry und (C) das Semantic Routing. Implementiere (A) den Content-Lifecycle, (B) die Edge-Registry und (C) das Semantic Routing.
---
### Teil A: Content Lifecycle (Ingestion Logic) ### Teil A: Content Lifecycle (Ingestion Logic)
Steuerung über Frontmatter `status`: Steuerung über Frontmatter `status`:
1. **System-Dateien (No-Index):** 1. **System-Dateien (No-Index):**
@@ -281,8 +282,6 @@ Steuerung über Frontmatter `status`:
* Wenn `status` in `['draft', 'active', 'stable']`: Status wird im Payload gespeichert. * 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`). * **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 ### Teil B: Central Edge Registry & Validation
1. **Registry Klasse:** 1. **Registry Klasse:**
* Erstelle `EdgeRegistry` (Singleton). * Erstelle `EdgeRegistry` (Singleton).
@@ -292,8 +291,6 @@ Steuerung über Frontmatter `status`:
* Prüfe beim Import jede Kante gegen die Registry. * 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). * 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) ### Teil C: Semantic Graph Routing (Dynamic Boosting)
**Ziel:** Die Bedeutung einer Kante soll sich je nach Frage-Typ ändern ("Warum" vs. "Wie"). **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. * Der `Retriever` erhält vom Router die `boost_edges` Map.
* Berechne Score: `BaseScore * (1 + ConfigWeight + DynamicBoost)`. * Berechne Score: `BaseScore * (1 + ConfigWeight + DynamicBoost)`.
---
**Deine Aufgaben:** **Deine Aufgaben:**
1. Zeige die `EdgeRegistry` Klasse (Parsing Logik). 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). 3. Zeige die Erweiterung in `scoring.py` (Status-Gewicht & Dynamic Edge Boosting).
Bitte bestätige die Übernahme dieses Architektur-Pakets. 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 ## 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). 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).
@@ -357,3 +355,81 @@ Stelle sicher, dass dir folgende Dateien vorliegen, um die Logik zu verstehen un
1. Entwurf eines `RecommenderService` für die Vektor-Suche in Qdrant. 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`. 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).
+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.
+2 -2
View File
@@ -2,13 +2,13 @@
doc_type: documentation_index doc_type: documentation_index
audience: all audience: all
status: active status: active
version: 2.9.1 version: 2.9.3
context: "Zentraler Einstiegspunkt für die Mindnet-Dokumentation" context: "Zentraler Einstiegspunkt für die Mindnet-Dokumentation"
--- ---
# Mindnet Dokumentation # Mindnet Dokumentation
Willkommen in der Dokumentation von Mindnet v2.9.1! Diese Dokumentation hilft dir dabei, das System zu verstehen, zu nutzen und weiterzuentwickeln. Willkommen in der Dokumentation von Mindnet v2.9.3! Diese Dokumentation hilft dir dabei, das System zu verstehen, zu nutzen und weiterzuentwickeln.
## 🚀 Schnellstart ## 🚀 Schnellstart