Compare commits

...
Author SHA1 Message Date
Lars b29ce4a0a6 scripts/health_check_mindnet.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-05 12:12:30 +01:00
Lars 311e598b69 scripts/health_check_mindnet.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-04 21:03:24 +01:00
Lars 413dca770c docs/wp04_retriever_scoring.md hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-04 20:38:00 +01:00
Lars 9d9239b11e app/core/retriever.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-04 15:55:39 +01:00
Lars a571c41c61 app/core/retriever.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-04 15:43:32 +01:00
Lars ba1fab9dcf config/retriever.yaml aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-04 15:43:00 +01:00
Lars 5dc9c13a71 tests/diag_subgraph_for_note.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-04 13:52:18 +01:00
Lars 70821bae5a tests/diag_edges_for_note.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-04 13:42:14 +01:00
Lars 486abf82dd tests/diag_edges_for_note.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-04 13:37:42 +01:00
Lars 19afe3af33 config/types.yaml aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-04 13:35:04 +01:00
Lars 113042b7f4 config/types.yaml aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 2s
2025-12-04 12:38:20 +01:00
Lars f8eebd91cb app/core/note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-04 12:37:31 +01:00
Lars 00297fc354 app/core/note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-04 12:11:51 +01:00
Lars 5baac082f9 app/core/graph_adapter.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-04 11:52:18 +01:00
Lars 611b0aa54e app/core/retriever.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-04 11:35:53 +01:00
Lars 110f0dbcf5 app/core/retriever.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-04 11:16:33 +01:00
Lars 1688cf0a1e app/core/graph_adapter.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-04 11:16:03 +01:00
Lars 13b7c8858a app/core/graph_adapter.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-03 18:40:06 +01:00
Lars b8b6f243d1 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-03 18:27:06 +01:00
Lars eaa6e805ce Dateien nach "config" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 5s
2025-12-03 18:26:18 +01:00
Lars 05dbb21c58 Dateien nach "tests" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-03 14:44:45 +01:00
Lars f1f4358dee app/core/note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-03 14:27:09 +01:00
Lars 3374c41f07 Dateien nach "docs" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-03 12:07:42 +01:00
Lars 95affe87e5 Dateien nach "tests" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 5s
2025-12-03 12:07:29 +01:00
Lars 5e86398fcd Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-03 12:03:37 +01:00
Lars 844f0cbe42 Dateien nach "tests" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-03 12:03:22 +01:00
Lars 4d5d7847e5 Dateien nach "tests" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 2s
2025-12-03 10:39:24 +01:00
Lars 06795feed6 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-03 10:39:11 +01:00
Lars a4548a7ee1 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-03 10:35:28 +01:00
Lars 42216865e2 app/core/retriever.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-02 17:37:06 +01:00
Lars e48bdb2401 tests/test_retriever_basic.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-02 17:32:40 +01:00
Lars c67eb4b2f3 app/core/retriever.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 6s
2025-12-02 17:31:49 +01:00
Lars fafa74b0b8 docs/mindnet_v2_implementation_playbook.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-18 11:19:22 +01:00
Lars 049a39aba3 docs/mindnet_technical_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-18 10:38:03 +01:00
Lars cd26430a61 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-11-18 07:52:39 +01:00
Lars aab010ff17 app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-18 07:50:46 +01:00
Lars 9a7bc32051 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-11-17 21:55:41 +01:00
Lars bfdd8ac6be app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 21:53:49 +01:00
Lars 018669fb87 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 21:44:03 +01:00
Lars fb2de78d62 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-11-17 21:42:26 +01:00
Lars 7e8d6c1954 app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 21:38:44 +01:00
Lars d21230c6c3 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 21:24:22 +01:00
Lars 4e98d5bfa1 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 21:23:49 +01:00
Lars 8998269377 app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 21:16:35 +01:00
Lars 6e9a227ad2 app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-11-17 21:05:36 +01:00
Lars 4e7506da5a config/types.yaml aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 19:37:56 +01:00
Lars 06ad93c77c config/types.yaml aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 19:36:56 +01:00
Lars 0bb7b34259 docs/mindnet_functional_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-11-17 18:46:39 +01:00
Lars 859c17b49d tests/test_edges_all.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 16:37:23 +01:00
Lars 46b26c9624 scripts/edges_full_check.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 16:37:00 +01:00
Lars fd215c18e4 app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 16:27:40 +01:00
Lars efa3afc7dc Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 16:18:10 +01:00
Lars e03dd66051 app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 5s
2025-11-17 16:14:57 +01:00
Lars 3476fe5fae tests/test_edges_smoke.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 16:04:57 +01:00
Lars 3e08c8347e scripts/edges_full_check.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-11-17 16:04:21 +01:00
Lars c691123d2d config/types.yaml aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 15:58:34 +01:00
Lars a4b81535e8 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 15:53:38 +01:00
Lars a898cf4b65 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 15:52:23 +01:00
Lars 10009a0a43 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 15:49:39 +01:00
Lars 4dfe47ff99 Dateien nach "app/core" hochladen
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 15:48:12 +01:00
Lars bd997e61d6 app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 15:46:56 +01:00
Lars 23d0670126 app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 15:39:18 +01:00
Lars 12c600edbe scripts/edges_full_check.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 15:31:58 +01:00
Lars e4115e705e tests/test_edges_all.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 15:31:36 +01:00
Lars 0cbc4a2d72 tests/test_edges_all.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 15:17:29 +01:00
Lars cea6d35729 scripts/edges_full_check.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-11-17 15:17:02 +01:00
Lars 4c56918d8a app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 13:06:29 +01:00
Lars f17263417e app/core/note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 12:21:59 +01:00
Lars 6f0b463489 app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 12:21:28 +01:00
Lars 28c01caa1a tests/test_edges_defaults_smoke.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 11:10:00 +01:00
Lars 95b59e9b0a app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 2s
2025-11-17 11:09:05 +01:00
Lars bc967f1f6e tests/test_edges_defaults_smoke.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 10:58:15 +01:00
Lars 4228b8a74f app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-11-17 10:57:30 +01:00
25 changed files with 4009 additions and 953 deletions

No files matched your search

+353 -38
View File
@@ -2,27 +2,45 @@
# -*- coding: utf-8 -*-
"""
Modul: app/core/derive_edges.py
Version: 1.4.0
Robuste Kantenbildung für mindnet (Notes/Chunks):
- belongs_to (chunk -> note)
- next / prev (chunk-Kette)
- references (chunk-scope) aus Chunk.window/text
- optional references/backlink (note-scope)
Wichtig: Wikilinks werden mit der Parser-Funktion `extract_wikilinks` extrahiert,
damit Varianten wie [[id#anchor]] oder [[id|label]] korrekt auf 'id' reduziert werden.
Zweck:
- Bewahrt bestehende Edgelogik (belongs_to, prev/next, references, backlink)
- Ergänzt typenbasierte Default-Kanten (edge_defaults aus config/types.yaml)
- Unterstützt "typed inline relations":
* [[rel:KIND | Target]]
* [[rel:KIND Target]]
* rel: KIND [[Target]]
- Unterstützt Obsidian-Callouts:
* > [!edge] KIND: [[Target]] [[Target2]] ...
Kompatibilität:
- build_edges_for_note(...) Signatur unverändert
- rule_id Werte:
* structure:belongs_to
* structure:order
* explicit:wikilink
* inline:rel
* callout:edge
* edge_defaults:<type>:<relation>
* derived:backlink
"""
from __future__ import annotations
from typing import Dict, List, Optional, Iterable
import os
import re
from typing import Iterable, List, Optional, Tuple, Set, Dict
# Parser-Extraktion für saubere Wikilinks
from app.core.parser import extract_wikilinks
try:
import yaml # optional, nur für types.yaml
except Exception: # pragma: no cover
yaml = None
# --------------------------------------------------------------------------- #
# Utilities
# --------------------------------------------------------------------------- #
def _get(d: dict, *keys, default=None):
for k in keys:
if k in d and d[k] is not None:
if isinstance(d, dict) and k in d and d[k] is not None:
return d[k]
return default
@@ -36,8 +54,8 @@ def _chunk_text_for_refs(chunk: dict) -> str:
or ""
)
def _dedupe(seq: Iterable[str]) -> List[str]:
seen = set()
def _dedupe_seq(seq: Iterable[str]) -> List[str]:
seen: Set[str] = set()
out: List[str] = []
for s in seq:
if s not in seen:
@@ -48,15 +66,177 @@ def _dedupe(seq: Iterable[str]) -> List[str]:
def _edge(kind: str, scope: str, source_id: str, target_id: str, note_id: str, extra: Optional[dict] = None) -> dict:
pl = {
"kind": kind,
"scope": scope, # "chunk" | "note"
"relation": kind, # Alias (v2)
"scope": scope, # "chunk" | "note"
"source_id": source_id,
"target_id": target_id,
"note_id": note_id, # Träger/Quelle der Kante (aktuelle Note)
"note_id": note_id, # Träger-Note der Kante
}
if extra:
pl.update(extra)
return pl
def _mk_edge_id(kind: str, s: str, t: str, scope: str, rule_id: Optional[str] = None) -> str:
base = f"{kind}:{s}->{t}#{scope}"
if rule_id:
base += f"|{rule_id}"
try:
import hashlib
return hashlib.blake2s(base.encode("utf-8"), digest_size=12).hexdigest()
except Exception: # pragma: no cover
return base
# --------------------------------------------------------------------------- #
# Typen-Registry (types.yaml)
# --------------------------------------------------------------------------- #
def _env(n: str, default: Optional[str] = None) -> str:
v = os.getenv(n)
return v if v is not None else (default or "")
def _load_types_registry() -> dict:
"""Lädt die YAML-Registry aus MINDNET_TYPES_FILE oder ./config/types.yaml"""
p = _env("MINDNET_TYPES_FILE", "./config/types.yaml")
if not os.path.isfile(p) or yaml is None:
return {}
try:
with open(p, "r", encoding="utf-8") as f:
data = yaml.safe_load(f) or {}
return data
except Exception:
return {}
def _get_types_map(reg: dict) -> dict:
if isinstance(reg, dict) and isinstance(reg.get("types"), dict):
return reg["types"]
return reg if isinstance(reg, dict) else {}
def _edge_defaults_for(note_type: Optional[str], reg: dict) -> List[str]:
"""
Liefert die edge_defaults-Liste für den gegebenen Notiztyp.
Fallback-Reihenfolge:
1) reg['types'][note_type]['edge_defaults']
2) reg['defaults']['edge_defaults'] (oder 'default'/'global')
3) []
"""
types_map = _get_types_map(reg)
if note_type and isinstance(types_map, dict):
t = types_map.get(note_type)
if isinstance(t, dict) and isinstance(t.get("edge_defaults"), list):
return [str(x) for x in t["edge_defaults"] if isinstance(x, str)]
for key in ("defaults", "default", "global"):
v = reg.get(key)
if isinstance(v, dict) and isinstance(v.get("edge_defaults"), list):
return [str(x) for x in v["edge_defaults"] if isinstance(x, str)]
return []
# --------------------------------------------------------------------------- #
# Parser für Links / Relationen
# --------------------------------------------------------------------------- #
# Normale Wikilinks (Fallback)
_WIKILINK_RE = re.compile(r"\[\[(?:[^\|\]]+\|)?([a-zA-Z0-9_\-#:. ]+)\]\]")
# Getypte Inline-Relationen:
# [[rel:KIND | Target]]
# [[rel:KIND Target]]
_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: KIND [[Target]] (reines Textmuster)
_REL_TEXT = re.compile(r"rel\s*:\s*(?P<kind>[a-z_]+)\s*\[\[\s*(?P<target>[^\]]+?)\s*\]\]", re.IGNORECASE)
def _extract_typed_relations(text: str) -> Tuple[List[Tuple[str,str]], str]:
"""
Gibt Liste (kind, target) zurück und den Text mit entfernten getypten Relation-Links,
damit die generische Wikilink-Erkennung sie nicht doppelt zählt.
Unterstützt drei Varianten:
- [[rel:KIND | Target]]
- [[rel:KIND Target]]
- rel: KIND [[Target]]
"""
pairs: List[Tuple[str,str]] = []
def _collect(m):
k = (m.group("kind") or "").strip().lower()
t = (m.group("target") or "").strip()
if k and t:
pairs.append((k, t))
return "" # Link entfernen
text = _REL_PIPE.sub(_collect, text)
text = _REL_SPACE.sub(_collect, text)
text = _REL_TEXT.sub(_collect, text)
return pairs, text
# Obsidian Callout Parser
_CALLOUT_START = re.compile(r"^\s*>\s*\[!edge\]\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"\[\[([^\]]+)\]\]")
def _extract_callout_relations(text: str) -> Tuple[List[Tuple[str,str]], str]:
"""
Findet [!edge]-Callouts und extrahiert (kind, target). Entfernt den gesamten
Callout-Block aus dem Text (damit Wikilinks daraus nicht zusätzlich als
"references" gezählt werden).
"""
if not text:
return [], text
lines = text.splitlines()
out_pairs: List[Tuple[str,str]] = []
keep_lines: List[str] = []
i = 0
while i < len(lines):
m = _CALLOUT_START.match(lines[i])
if not m:
keep_lines.append(lines[i])
i += 1
continue
block_lines: List[str] = []
first_rest = m.group(1) or ""
if first_rest.strip():
block_lines.append(first_rest)
i += 1
while i < len(lines) and lines[i].lstrip().startswith('>'):
block_lines.append(lines[i].lstrip()[1:].lstrip())
i += 1
for bl in block_lines:
mrel = _REL_LINE.match(bl)
if not mrel:
continue
kind = (mrel.group("kind") or "").strip().lower()
targets = mrel.group("targets") or ""
found = _WIKILINKS_IN_LINE.findall(targets)
if found:
for t in found:
t = t.strip()
if t:
out_pairs.append((kind, t))
else:
for raw in re.split(r"[,;]", targets):
t = raw.strip()
if t:
out_pairs.append((kind, t))
# Callout wird NICHT in keep_lines übernommen
continue
remainder = "\n".join(keep_lines)
return out_pairs, remainder
def _extract_wikilinks(text: str) -> List[str]:
ids: List[str] = []
for m in _WIKILINK_RE.finditer(text or ""):
ids.append(m.group(1).strip())
return ids
# --------------------------------------------------------------------------- #
# Hauptfunktion
# --------------------------------------------------------------------------- #
def build_edges_for_note(
note_id: str,
chunks: List[dict],
@@ -68,53 +248,188 @@ def build_edges_for_note(
- belongs_to: für jeden Chunk (chunk -> note)
- next / prev: zwischen aufeinanderfolgenden Chunks
- references: pro Chunk aus window/text
- references: pro Chunk aus window/text (via Wikilinks)
- typed inline relations: [[rel:KIND | Target]] / [[rel:KIND Target]] / rel: KIND [[Target]]
- Obsidian Callouts: > [!edge] KIND: [[Target]] [[Target2]]
- optional note-scope references/backlinks: dedupliziert über alle Chunk-Funde + note_level_references
- typenbasierte Default-Kanten (edge_defaults) je gefundener Referenz
"""
edges: List[dict] = []
# belongs_to
# Note-Typ (aus erstem Chunk erwartet)
note_type = None
if chunks:
note_type = _get(chunks[0], "type")
# 1) belongs_to
for ch in chunks:
cid = _get(ch, "chunk_id", "id")
if not cid:
continue
edges.append(_edge("belongs_to", "chunk", cid, note_id, note_id, {"chunk_id": cid}))
edges.append(_edge("belongs_to", "chunk", cid, note_id, note_id, {
"chunk_id": cid,
"edge_id": _mk_edge_id("belongs_to", cid, note_id, "chunk", "structure:belongs_to"),
"provenance": "rule",
"rule_id": "structure:belongs_to",
"confidence": 1.0,
}))
# next/prev
# 2) next / prev
for i in range(len(chunks) - 1):
a, b = chunks[i], chunks[i + 1]
a_id = _get(a, "chunk_id", "id")
b_id = _get(b, "chunk_id", "id")
if not a_id or not b_id:
continue
edges.append(_edge("next", "chunk", a_id, b_id, note_id, {"chunk_id": a_id}))
edges.append(_edge("prev", "chunk", b_id, a_id, note_id, {"chunk_id": b_id}))
edges.append(_edge("next", "chunk", a_id, b_id, note_id, {
"chunk_id": a_id,
"edge_id": _mk_edge_id("next", a_id, b_id, "chunk", "structure:order"),
"provenance": "rule",
"rule_id": "structure:order",
"confidence": 0.95,
}))
edges.append(_edge("prev", "chunk", b_id, a_id, note_id, {
"chunk_id": b_id,
"edge_id": _mk_edge_id("prev", b_id, a_id, "chunk", "structure:order"),
"provenance": "rule",
"rule_id": "structure:order",
"confidence": 0.95,
}))
# references (chunk-scope) – Links aus window bevorzugen (Overlap-fest)
# 3) references + typed inline + callouts + defaults (chunk-scope)
reg = _load_types_registry()
defaults = _edge_defaults_for(note_type, reg)
refs_all: List[str] = []
for ch in chunks:
cid = _get(ch, "chunk_id", "id")
if not cid:
continue
txt = _chunk_text_for_refs(ch)
refs = extract_wikilinks(txt) # Parser-Logik
raw = _chunk_text_for_refs(ch)
# 3a) typed inline relations
typed, remainder = _extract_typed_relations(raw)
for kind, target in typed:
kind = kind.strip().lower()
if not kind or not target:
continue
edges.append(_edge(kind, "chunk", cid, target, note_id, {
"chunk_id": cid,
"edge_id": _mk_edge_id(kind, cid, target, "chunk", "inline:rel"),
"provenance": "explicit",
"rule_id": "inline:rel",
"confidence": 0.95,
}))
if kind in {"related_to", "similar_to"}:
edges.append(_edge(kind, "chunk", target, cid, note_id, {
"chunk_id": cid,
"edge_id": _mk_edge_id(kind, target, cid, "chunk", "inline:rel"),
"provenance": "explicit",
"rule_id": "inline:rel",
"confidence": 0.95,
}))
# 3b) callouts
call_pairs, remainder2 = _extract_callout_relations(remainder)
for kind, target in call_pairs:
k = (kind or "").strip().lower()
if not k or not target:
continue
edges.append(_edge(k, "chunk", cid, target, note_id, {
"chunk_id": cid,
"edge_id": _mk_edge_id(k, cid, target, "chunk", "callout:edge"),
"provenance": "explicit",
"rule_id": "callout:edge",
"confidence": 0.95,
}))
if k in {"related_to", "similar_to"}:
edges.append(_edge(k, "chunk", target, cid, note_id, {
"chunk_id": cid,
"edge_id": _mk_edge_id(k, target, cid, "chunk", "callout:edge"),
"provenance": "explicit",
"rule_id": "callout:edge",
"confidence": 0.95,
}))
# 3c) generische Wikilinks → references (+ defaults je Ref)
refs = _extract_wikilinks(remainder2)
for r in refs:
edges.append(_edge("references", "chunk", cid, r, note_id, {"chunk_id": cid, "ref_text": r}))
edges.append(_edge("references", "chunk", cid, r, note_id, {
"chunk_id": cid,
"ref_text": r,
"edge_id": _mk_edge_id("references", cid, r, "chunk", "explicit:wikilink"),
"provenance": "explicit",
"rule_id": "explicit:wikilink",
"confidence": 1.0,
}))
for rel in defaults:
if rel == "references":
continue
edges.append(_edge(rel, "chunk", cid, r, note_id, {
"chunk_id": cid,
"edge_id": _mk_edge_id(rel, cid, r, "chunk", f"edge_defaults:{note_type}:{rel}"),
"provenance": "rule",
"rule_id": f"edge_defaults:{note_type}:{rel}",
"confidence": 0.7,
}))
if rel in {"related_to", "similar_to"}:
edges.append(_edge(rel, "chunk", r, cid, note_id, {
"chunk_id": cid,
"edge_id": _mk_edge_id(rel, r, cid, "chunk", f"edge_defaults:{note_type}:{rel}"),
"provenance": "rule",
"rule_id": f"edge_defaults:{note_type}:{rel}",
"confidence": 0.7,
}))
refs_all.extend(refs)
# optional: note-scope references/backlinks
# 4) optional note-scope refs/backlinks (+ defaults)
if include_note_scope_refs:
refs_note = refs_all[:]
refs_note = list(refs_all or [])
if note_level_references:
refs_note.extend([r for r in note_level_references if isinstance(r, str) and r])
refs_note = _dedupe(refs_note)
refs_note = _dedupe_seq(refs_note)
for r in refs_note:
edges.append(_edge("references", "note", note_id, r, note_id))
edges.append(_edge("backlink", "note", r, note_id, 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"),
"provenance": "explicit",
"rule_id": "explicit:note_scope",
"confidence": 1.0,
}))
edges.append(_edge("backlink", "note", r, note_id, note_id, {
"edge_id": _mk_edge_id("backlink", r, note_id, "note", "derived:backlink"),
"provenance": "rule",
"rule_id": "derived:backlink",
"confidence": 0.9,
}))
for rel in defaults:
if rel == "references":
continue
edges.append(_edge(rel, "note", note_id, r, note_id, {
"edge_id": _mk_edge_id(rel, note_id, r, "note", f"edge_defaults:{note_type}:{rel}"),
"provenance": "rule",
"rule_id": f"edge_defaults:{note_type}:{rel}",
"confidence": 0.7,
}))
if rel in {"related_to", "similar_to"}:
edges.append(_edge(rel, "note", r, note_id, note_id, {
"edge_id": _mk_edge_id(rel, r, note_id, "note", f"edge_defaults:{note_type}:{rel}"),
"provenance": "rule",
"rule_id": f"edge_defaults:{note_type}:{rel}",
"confidence": 0.7,
}))
# Dedupe (Schlüssel: kind,source_id,target_id,scope)
dedup = {}
# 5) De-Dupe (source_id, target_id, relation, rule_id)
seen: Set[Tuple[str,str,str,str]] = set()
out: List[dict] = []
for e in edges:
k = (e["kind"], e["source_id"], e["target_id"], e.get("scope", ""))
dedup[k] = e
return list(dedup.values())
s = str(e.get("source_id") or "")
t = str(e.get("target_id") or "")
rel = str(e.get("relation") or e.get("kind") or "edge")
rule = str(e.get("rule_id") or "")
key = (s, t, rel, rule)
if key in seen:
continue
seen.add(key)
out.append(e)
return out
+252 -39
View File
@@ -1,90 +1,303 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
app/core/graph_adapter.py — Adjazenzaufbau & Subgraph-Expansion (WP-04)
Zweck:
Baut aus Qdrant-Edges (Collection: *_edges) einen leichten In-Memory-Graph
und liefert Edge-basierte Kennzahlen (In-Degree, Out-Degree, edge_bonus).
Kompatibilität:
Python 3.12+, qdrant-client 1.x
- Python 3.12+, qdrant-client 1.x
- Wird von app/core/retriever.py im Hybrid-Modus genutzt.
- Signaturen bleiben kompatibel zu den bestehenden Tests
(tests/test_retriever_edges.py patcht expand()).
Version:
0.1.0 (Erstanlage)
Stand:
2025-10-07
Bezug:
- WP-04 Edge-Gewichtungen und Heuristiken
- app/core/qdrant_points.py (get_edges_for_sources)
Nutzung:
from app.core.graph_adapter import expand
Änderungsverlauf:
0.1.0 (2025-10-07) – Erstanlage.
0.3.1 (2025-12-04 – note_id-bewusste Expansion:
* Seeds = Note-IDs
* Subgraph pflegt zusätzlich Adjazenz auf note_id-Basis,
damit der Retriever mit note_id arbeiten kann)
"""
from __future__ import annotations
from typing import Dict, List, Optional, DefaultDict
from collections import defaultdict
from qdrant_client import QdrantClient
from app.core.qdrant_points import get_edges_for_sources
EDGE_BASE_WEIGHTS = {
"references": 0.20,
"belongs_to": 0.10,
"next": 0.06,
"prev": 0.06,
"backlink": 0.04,
"references_at": 0.08,
from qdrant_client import QdrantClient
from qdrant_client.http import models as rest
from app.core.qdrant import collection_names
# Legacy-Import (wird aktuell nicht mehr verwendet, bleibt aber erhalten,
# damit bestehende Importe/Mocks nicht brechen).
try: # pragma: no cover
from app.core.qdrant_points import get_edges_for_sources # type: ignore
except Exception: # pragma: no cover
get_edges_for_sources = None # type: ignore
# Basisgewichte je Edge-Typ.
# Diese Werte werden mit der in der Edge-Payload hinterlegten "confidence"
# multipliziert, falls vorhanden.
#
# Hinweis:
# - Strukturkanten (belongs_to, next/prev) sind schwächer gewichtet.
# - Wissenskanten (depends_on, related_to, similar_to, references) erhalten
# höhere Basisgewichte, damit sie sich im Retriever bemerkbar machen.
EDGE_BASE_WEIGHTS: Dict[str, float] = {
# Struktur / Navigationskanten
"belongs_to": 0.10,
"next": 0.06,
"prev": 0.06,
"backlink": 0.04,
"references_at": 0.08,
# Wissenskanten
"references": 0.20,
"depends_on": 0.18,
"related_to": 0.15,
"similar_to": 0.12,
# weitere Typen erhalten per Default 0.0 und wirken nur über centrality
}
def _edge_weight(pl: Dict) -> float:
"""Berechnet das effektive Edge-Gewicht aus kind + confidence."""
kind = pl.get("kind", "edge")
base = EDGE_BASE_WEIGHTS.get(kind, 0.0)
conf_raw = pl.get("confidence", None)
try:
conf = float(conf_raw) if conf_raw is not None else None
except Exception:
conf = None
if conf is None:
return base
# Confidence vorsichtig in [0.0, 1.0] clampen
if conf < 0.0:
conf = 0.0
if conf > 1.0:
conf = 1.0
return base * conf
def _fetch_edges(
client: QdrantClient,
prefix: str,
seeds: List[str],
edge_types: Optional[List[str]] = None,
limit: int = 2048,
) -> List[Dict]:
"""
Holt Edges direkt aus der *_edges Collection.
Filter:
- source_id IN seeds ODER target_id IN seeds ODER note_id IN seeds
- optional: kind IN edge_types
"""
if not seeds or limit <= 0:
return []
_, _, edges_col = collection_names(prefix)
# OR über source_id / target_id / note_id für alle Seeds
seed_conditions = []
for field in ("source_id", "target_id", "note_id"):
for s in seeds:
seed_conditions.append(
rest.FieldCondition(
key=field,
match=rest.MatchValue(value=str(s)),
)
)
seeds_filter = rest.Filter(should=seed_conditions) if seed_conditions else None
# Optional: Filter auf bestimmte Edge-Typen (kind)
type_filter = None
if edge_types:
type_conds = [
rest.FieldCondition(
key="kind",
match=rest.MatchValue(value=str(k)),
)
for k in edge_types
]
type_filter = rest.Filter(should=type_conds)
flt = None
must = []
if seeds_filter:
must.append(seeds_filter)
if type_filter:
must.append(type_filter)
if must:
flt = rest.Filter(must=must)
pts, _ = client.scroll(
collection_name=edges_col,
scroll_filter=flt,
limit=limit,
with_payload=True,
with_vectors=False,
)
out: List[Dict] = []
for p in pts or []:
pl = dict(p.payload or {})
if pl:
out.append(pl)
return out
class Subgraph:
"""Leichtgewichtiger Subgraph mit Adjazenzlisten & einfachen Kennzahlen."""
def __init__(self):
def __init__(self) -> None:
self.adj: DefaultDict[str, List[Dict]] = defaultdict(list)
self.in_degree: DefaultDict[str, int] = defaultdict(int)
self.out_degree: DefaultDict[str, int] = defaultdict(int)
def add_edge(self, e: Dict):
src = e["source"]; tgt = e["target"]; kind = e["kind"]
def add_edge(self, e: Dict) -> None:
"""
Fügt eine Kante zum Subgraph hinzu.
e enthält:
- source: Knoten-ID (z. B. source_id)
- target: Knoten-ID (z. B. target_id)
- kind: Kantentyp
- weight: bereits berechnetes Gewicht
- note_id: (optional) Kontext-Note dieser Kante
Wichtig für den Retriever:
- Wir pflegen Adjazenz primär unter `source`.
- Zusätzlich pflegen wir, falls vorhanden, eine Adjazenz
unter `note_id`, damit der Retriever mit note_id arbeiten kann.
"""
src = e.get("source")
tgt = e.get("target")
kind = e.get("kind")
weight = e.get("weight", EDGE_BASE_WEIGHTS.get(kind, 0.0))
self.adj[src].append({"target": tgt, "kind": kind, "weight": weight})
owner = e.get("note_id")
if not src or not tgt:
return
# Primäre Adjazenz (z. B. source_id → target_id)
self.adj[src].append(
{
"target": tgt,
"kind": kind,
"weight": weight,
}
)
self.out_degree[src] += 1
self.in_degree[tgt] += 1
# Sekundäre Adjazenz auf Note-Ebene:
# Falls eine Kontext-Note existiert, bekommt diese ebenfalls
# "Ausgangskanten" angerechnet. So kann der Retriever über note_id
# edge_bonus(...) und centrality_bonus(...) abfragen.
if owner:
# same edge unter owner registrieren (falls nicht identisch mit src),
# damit edge_bonus(owner) > 0 werden kann.
if owner != src:
self.adj[owner].append(
{
"target": tgt,
"kind": kind,
"weight": weight,
}
)
self.out_degree[owner] += 1
# Zentralität der Kontext-Note leicht erhöhen
if owner != tgt:
self.in_degree[owner] += 1
def aggregate_edge_bonus(self, node_id: str) -> float:
"""
Summe der ausgehenden Kantengewichte für einen Knoten.
"""
return sum(edge["weight"] for edge in self.adj.get(node_id, []))
def edge_bonus(self, node_id: str) -> float:
"""
Kompatibilitäts-Methode für den Retriever.
Der Retriever ruft subgraph.edge_bonus(node_id) auf. Intern verwenden
wir aggregate_edge_bonus(...), um bestehende Tests nicht zu brechen.
"""
return self.aggregate_edge_bonus(node_id)
def centrality_bonus(self, node_id: str) -> float:
"""
Einfache log-gedämpfte Zentralität auf Basis des In-Degree.
Obergrenze: 0.15
"""
import math
# Log-gedämpfter Bonus, hart begrenzt
return min(math.log1p(self.in_degree.get(node_id, 0)) / 10.0, 0.15)
indeg = self.in_degree.get(node_id, 0)
if indeg <= 0:
return 0.0
return min(math.log1p(indeg) / 10.0, 0.15)
def expand(client: QdrantClient, prefix: str, seeds: List[str],
depth: int = 1, edge_types: Optional[List[str]] = None) -> Subgraph:
def expand(
client: QdrantClient,
prefix: str,
seeds: List[str],
depth: int = 1,
edge_types: Optional[List[str]] = None,
) -> Subgraph:
"""
Expandiert ab Seeds entlang von Edges (bis depth), optional gefiltert nach Typen.
Seeds sind stabile payload-IDs (z. B. note_id, chunk_id).
Expandiert ab Seeds entlang von Edges (bis `depth`), optional gefiltert
nach Edge-Typen.
Seeds sind stabile payload-IDs (in unserem Fall vor allem note_id).
Es werden Edges berücksichtigt, bei denen source_id ODER target_id ODER
note_id einem der Seeds entspricht.
"""
sg = Subgraph()
frontier = set(seeds)
visited = set()
for _ in range(max(depth, 0)):
max_depth = max(depth, 0)
for _ in range(max_depth):
if not frontier:
break
edges = get_edges_for_sources(client, prefix, list(frontier), edge_types=edge_types, limit=2048)
edges_payloads = _fetch_edges(
client=client,
prefix=prefix,
seeds=list(frontier),
edge_types=edge_types,
limit=2048,
)
next_frontier = set()
for pl in edges:
for pl in edges_payloads:
src = pl.get("source_id")
tgt = pl.get("target_id")
kind = pl.get("kind", "edge")
owner = pl.get("note_id")
e = {
"source": pl.get("source_id"),
"target": pl.get("target_id"),
"kind": pl.get("kind", "edge"),
"weight": pl.get("weight", EDGE_BASE_WEIGHTS.get(pl.get("kind", "edge"), 0.0)),
"source": src,
"target": tgt,
"kind": kind,
"weight": _edge_weight(pl),
"note_id": owner,
}
sg.add_edge(e)
if e["target"]:
next_frontier.add(e["target"])
if tgt:
next_frontier.add(tgt)
visited |= frontier
frontier = next_frontier - visited
+196 -129
View File
@@ -1,159 +1,226 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
app/core/note_payload.py (Mindnet V2 — types.yaml authoritative)
- retriever_weight und chunk_profile werden aus config/types.yaml gelesen.
- Reihenfolge: types.<type> > defaults.* > Fallbacks (1.0 / "default").
- Frontmatter-Overrides für diese beiden Felder werden bewusst IGNORIERT.
- edge_defaults (falls in types.yaml definiert) werden in die Note-Payload gespiegelt.
- MINDNET_TYPES_FILE kann absoluten Pfad liefern, sonst ./config/types.yaml.
Modul: app/core/note_payload.py
Version: 2.0.0
Zweck
-----
Erzeugt ein robustes Note-Payload. Werte wie `retriever_weight`, `chunk_profile`
und `edge_defaults` werden in folgender Priorität bestimmt:
1) Frontmatter (Note)
2) Typ-Registry (config/types.yaml: types.<type>.*)
3) Registry-Defaults (config/types.yaml: defaults.*)
4) ENV-Defaults (MINDNET_DEFAULT_RETRIEVER_WEIGHT / MINDNET_DEFAULT_CHUNK_PROFILE)
"""
from __future__ import annotations
from typing import Any, Dict, Optional, List
import os, yaml, hashlib, datetime
# ----------------------- helpers -----------------------
from typing import Any, Dict, Tuple, Optional
import os
import json
import pathlib
def _env(n: str, d: Optional[str]=None) -> str:
v = os.getenv(n)
return v if v is not None else (d or "")
try:
import yaml # type: ignore
except Exception:
yaml = None
def _load_types() -> dict:
p = _env("MINDNET_TYPES_FILE", "./config/types.yaml")
# ---------------------------------------------------------------------------
# Helper
# ---------------------------------------------------------------------------
def _as_dict(x) -> Dict[str, Any]:
"""Versucht, ein ParsedMarkdown-ähnliches Objekt in ein Dict zu überführen."""
if isinstance(x, dict):
return dict(x)
out: Dict[str, Any] = {}
# bekannte Attribute übernehmen, sofern vorhanden
for attr in (
"frontmatter",
"body",
"id",
"note_id",
"title",
"path",
"tags",
"type",
"created",
"modified",
"date",
):
if hasattr(x, attr):
val = getattr(x, attr)
if val is not None:
out[attr] = val
# Fallback: wenn immer noch leer, raw speichern
if not out:
out["raw"] = str(x)
return out
def _pick_args(*args, **kwargs) -> Tuple[Optional[str], Optional[dict]]:
"""Extrahiert optionale Zusatzargumente wie path und types_cfg."""
path = kwargs.get("path") or (args[0] if args else None)
types_cfg = kwargs.get("types_cfg") or kwargs.get("types") or None
return path, types_cfg
def _env_float(name: str, default: float) -> float:
"""Liest einen Float-Wert aus der Umgebung, mit robustem Fallback."""
try:
with open(p, "r", encoding="utf-8") as f:
return yaml.safe_load(f) or {}
return float(os.environ.get(name, default))
except Exception:
return default
def _ensure_list(x) -> list:
"""Garantiert eine String-Liste."""
if x is None:
return []
if isinstance(x, list):
return [str(i) for i in x]
if isinstance(x, (set, tuple)):
return [str(i) for i in x]
return [str(x)]
# ---------------------------------------------------------------------------
# Type-Registry laden
# ---------------------------------------------------------------------------
def _load_types_config(explicit_cfg: Optional[dict] = None) -> dict:
"""Lädt die Type-Registry aus YAML/JSON oder nutzt ein explizit übergebenes Dict."""
if explicit_cfg and isinstance(explicit_cfg, dict):
return explicit_cfg
path = os.getenv("MINDNET_TYPES_FILE") or "./config/types.yaml"
if not os.path.isfile(path) or yaml is None:
return {}
try:
with open(path, "r", encoding="utf-8") as f:
data = yaml.safe_load(f) or {}
return data if isinstance(data, dict) else {}
except Exception:
return {}
def _get_types_map(reg: dict) -> dict:
if isinstance(reg, dict) and isinstance(reg.get("types"), dict):
return reg["types"]
return reg if isinstance(reg, dict) else {}
def _get_defaults(reg: dict) -> dict:
if isinstance(reg, dict) and isinstance(reg.get("defaults"), dict):
return reg["defaults"]
# alias "global" erlaubt
if isinstance(reg, dict) and isinstance(reg.get("global"), dict):
return reg["global"]
def _cfg_for_type(note_type: str, reg: dict) -> dict:
"""Liefert die Konfiguration für einen konkreten Notiztyp aus der Registry."""
if not isinstance(reg, dict):
return {}
types = reg.get("types") if isinstance(reg.get("types"), dict) else reg
return types.get(note_type, {}) if isinstance(types, dict) else {}
def _cfg_defaults(reg: dict) -> dict:
"""Liefert den Default-Block aus der Registry (defaults/global)."""
if not isinstance(reg, dict):
return {}
for key in ("defaults", "default", "global"):
v = reg.get(key)
if isinstance(v, dict):
return v
return {}
def _resolve_chunk_profile(note_type: str, reg: dict) -> str:
types = _get_types_map(reg)
if isinstance(types, dict):
t = types.get(note_type, {})
if isinstance(t, dict) and isinstance(t.get("chunk_profile"), str):
return t["chunk_profile"]
defs = _get_defaults(reg)
if isinstance(defs, dict) and isinstance(defs.get("chunk_profile"), str):
return defs["chunk_profile"]
return "default"
def _as_float(x: Any) -> Optional[float]:
# ---------------------------------------------------------------------------
# Haupt-API
# ---------------------------------------------------------------------------
def make_note_payload(note: Any, *args, **kwargs) -> Dict[str, Any]:
"""
Baut das Note-Payload für mindnet_notes auf.
Erwartete Felder im Payload:
- note_id: stabile ID aus Frontmatter (id) oder Note-Objekt
- title: Titel der Notiz
- type: Notiztyp (z. B. concept, project, journal, ...)
- path: Pfad im Vault
- retriever_weight: effektives Gewicht für den Retriever
- chunk_profile: Profil für Chunking (short|medium|long|default|...)
- edge_defaults: Liste von Kanten-Typen, die als Defaults gelten
"""
n = _as_dict(note)
path_arg, types_cfg_explicit = _pick_args(*args, **kwargs)
reg = _load_types_config(types_cfg_explicit)
fm = n.get("frontmatter") or {}
fm_type = fm.get("type") or n.get("type") or "concept"
note_type = str(fm_type)
cfg_type = _cfg_for_type(note_type, reg)
cfg_def = _cfg_defaults(reg)
# --- retriever_weight: Frontmatter > Typ-Config > Registry-Defaults > ENV ---
default_rw = _env_float("MINDNET_DEFAULT_RETRIEVER_WEIGHT", 1.0)
retriever_weight = fm.get("retriever_weight")
if retriever_weight is None:
retriever_weight = cfg_type.get(
"retriever_weight",
cfg_def.get("retriever_weight", default_rw),
)
try:
return float(x)
retriever_weight = float(retriever_weight)
except Exception:
return None
retriever_weight = default_rw
def _resolve_retriever_weight(note_type: str, reg: dict) -> float:
types = _get_types_map(reg)
if isinstance(types, dict):
t = types.get(note_type, {})
if isinstance(t, dict) and (t.get("retriever_weight") is not None):
v = _as_float(t.get("retriever_weight"))
if v is not None:
return float(v)
defs = _get_defaults(reg)
if isinstance(defs, dict) and (defs.get("retriever_weight") is not None):
v = _as_float(defs.get("retriever_weight"))
if v is not None:
return float(v)
return 1.0
# --- chunk_profile: Frontmatter > Typ-Config > Registry-Defaults > ENV ---
chunk_profile = fm.get("chunk_profile")
if chunk_profile is None:
chunk_profile = cfg_type.get(
"chunk_profile",
cfg_def.get(
"chunk_profile",
os.environ.get("MINDNET_DEFAULT_CHUNK_PROFILE", "medium"),
),
)
if not isinstance(chunk_profile, str):
chunk_profile = "medium"
# ------------------- public API -------------------
# --- edge_defaults: Frontmatter > Typ-Config > Registry-Defaults ---
edge_defaults = fm.get("edge_defaults")
if edge_defaults is None:
edge_defaults = cfg_type.get(
"edge_defaults",
cfg_def.get("edge_defaults", []),
)
edge_defaults = _ensure_list(edge_defaults)
def make_note_payload(parsed_note: Any,
*,
vault_root: str,
hash_mode: str = "body",
hash_normalize: str = "canonical",
hash_source: str = "parsed",
file_path: Optional[str] = None) -> Dict[str, Any]:
"""
Erwartet ein Parsed-Objekt mit Attributen:
- frontmatter (dict)
- body (str)
- path (optional)
Liefert Note-Payload mit deterministischer note_id und Typ-Werten aus types.yaml.
"""
fm = (getattr(parsed_note, "frontmatter", None) or {}) if parsed_note else {}
title = fm.get("title") or ""
note_type = fm.get("type") or "concept"
note_id = fm.get("id") or _stable_id_from_path_or_title(file_path or "", title)
tags = fm.get("tags") or []
if isinstance(tags, str):
tags = [tags]
# types.yaml authoritative:
reg = _load_types()
chunk_profile = _resolve_chunk_profile(note_type, reg)
retriever_weight = _resolve_retriever_weight(note_type, reg)
# edge_defaults (falls vorhanden)
edge_defaults = None
types = _get_types_map(reg)
if isinstance(types, dict):
t = types.get(note_type, {})
if isinstance(t, dict) and isinstance(t.get("edge_defaults"), list):
edge_defaults = t["edge_defaults"]
updated = _ts_to_int(fm.get("updated"))
# --- Basis-Metadaten (IDs, Titel, Pfad) ---
note_id = n.get("note_id") or n.get("id") or fm.get("id")
title = n.get("title") or fm.get("title") or ""
path = n.get("path") or path_arg
if isinstance(path, pathlib.Path):
path = str(path)
payload: Dict[str, Any] = {
"note_id": note_id,
"type": note_type,
"title": title,
"tags": tags,
"updated": updated if updated is not None else 0,
"path": file_path or "",
"type": note_type,
"path": path or "",
"retriever_weight": retriever_weight,
"chunk_profile": chunk_profile,
"retriever_weight": float(retriever_weight),
"edge_defaults": edge_defaults,
}
if edge_defaults is not None:
payload["edge_defaults"] = edge_defaults
# Tags / Keywords übernehmen
tags = fm.get("tags") or fm.get("keywords") or n.get("tags")
if tags:
payload["tags"] = _ensure_list(tags)
# Zeitliche Metadaten (sofern vorhanden)
for k in ("created", "modified", "date"):
v = fm.get(k) or n.get(k)
if v:
payload[k] = str(v)
# JSON-Roundtrip zur harten Validierung (ASCII beibehalten)
json.loads(json.dumps(payload, ensure_ascii=False))
return payload
# ------------------- internal utilities -------------------
def _stable_id_from_path_or_title(path: str, title: str) -> str:
base = path or title or ""
if not base:
base = "note"
h = hashlib.sha1(base.encode("utf-8")).hexdigest()[:6]
# title-sourced; in V2 typischerweise durch Frontmatter id ersetzt
return f"auto-{h}"
def _ts_to_int(val: Any) -> Optional[int]:
# akzeptiert YYYY-MM-DD oder epoch int; None bei Fehler
if val is None:
return None
if isinstance(val, int):
return val
if isinstance(val, float):
return int(val)
if isinstance(val, str):
val = val.strip()
# YYYY-MM-DD
try:
dt = datetime.date.fromisoformat(val)
return int(datetime.datetime(dt.year, dt.month, dt.day).timestamp())
except Exception:
pass
# epoch string
try:
return int(val)
except Exception:
return None
return None
+81
View File
@@ -217,3 +217,84 @@ def search_chunks_by_vector(client: QdrantClient, prefix: str, vector: List[floa
for r in res:
out.append((str(r.id), float(r.score), dict(r.payload or {})))
return out
# --- Edge retrieval helper ---
def get_edges_for_sources(
client: QdrantClient,
prefix: str,
source_ids: Iterable[str],
edge_types: Optional[Iterable[str]] = None,
limit: int = 2048,
) -> List[Dict[str, Any]]:
"""Retrieve edge payloads from the <prefix>_edges collection.
Args:
client: QdrantClient instance.
prefix: Mindnet collection prefix (e.g. "mindnet").
source_ids: Iterable of source_id values (typically chunk_ids or note_ids).
edge_types: Optional iterable of edge kinds (e.g. ["references", "depends_on"]). If None,
all kinds are returned.
limit: Maximum number of edge payloads to return.
Returns:
A list of edge payload dicts, e.g.:
{
"note_id": "...",
"chunk_id": "...",
"kind": "references" | "depends_on" | ...,
"scope": "chunk",
"source_id": "...",
"target_id": "...",
"rule_id": "...",
"confidence": 0.7,
...
}
"""
source_ids = list(source_ids)
if not source_ids or limit <= 0:
return []
# Resolve collection name
_, _, edges_col = _names(prefix)
# Build filter: source_id IN source_ids
src_filter = _filter_any("source_id", [str(s) for s in source_ids])
# Optional: kind IN edge_types
kind_filter = None
if edge_types:
kind_filter = _filter_any("kind", [str(k) for k in edge_types])
flt = _merge_filters(src_filter, kind_filter)
out: List[Dict[str, Any]] = []
next_page = None
remaining = int(limit)
# Use paginated scroll API; we don't need vectors, only payloads.
while remaining > 0:
batch_limit = min(256, remaining)
res, next_page = client.scroll(
collection_name=edges_col,
scroll_filter=flt,
limit=batch_limit,
with_payload=True,
with_vectors=False,
offset=next_page,
)
if not res:
break
for r in res:
out.append(dict(r.payload or {}))
remaining -= 1
if remaining <= 0:
break
if next_page is None or remaining <= 0:
break
return out
+277 -98
View File
@@ -1,121 +1,300 @@
"""
app/core/retriever.py — Semantischer/Edge-Aware/Hybrid Retriever (WP-04)
Zweck:
Kandidatenfindung via Vektorsuche in *_chunks, optionale Edge-Expansion
und kombiniertes Ranking zur Rückgabe von Top-K Treffern.
Erweiterung (0.2.0): Text→Embedding, falls kein query_vector übergeben wurde.
Kompatibilität:
Python 3.12+, qdrant-client 1.x
Version:
0.2.0 (Text→Embedding ergänzt; bestehendes Verhalten unverändert)
Stand:
2025-10-07
Bezug:
- app/core/graph_adapter.py (expand)
- app/core/ranking.py (combine_scores)
- app/core/qdrant_points.py (search_chunks_by_vector)
- app/services/embeddings_client.py (embed_text)
- app/models/dto.py (QueryRequest/Response)
Änderungsverlauf:
0.2.0 (2025-10-07) – Text→Embedding (embed_text_if_needed).
0.1.0 (2025-10-07) – Erstanlage.
"""
from __future__ import annotations
import os
import time
from typing import Dict, List, Optional, Tuple
from qdrant_client import QdrantClient
from functools import lru_cache
from typing import Any, Dict, List, Tuple, Iterable
from app.models.dto import QueryRequest, QueryResponse, QueryHit
from app.core.ranking import combine_scores
from app.core.graph_adapter import expand
from app.core import qdrant_points as qp
from app.config import get_settings
from app.services.embeddings_client import embed_text
from app.models.dto import QueryRequest, QueryResponse, QueryHit
import app.core.qdrant as qdr
import app.core.qdrant_points as qp
import app.services.embeddings_client as ec
import app.core.graph_adapter as ga
try:
import yaml # type: ignore[import]
except Exception: # pragma: no cover - Fallback, falls PyYAML nicht installiert ist
yaml = None # type: ignore[assignment]
def _vector_from_request(req: QueryRequest) -> List[float]:
@lru_cache
def _get_scoring_weights() -> Tuple[float, float, float]:
"""Liefert (semantic_weight, edge_weight, centrality_weight) für den Retriever.
Priorität:
1. Werte aus config/retriever.yaml (falls vorhanden und gültig),
Abschnitt:
scoring:
semantic_weight: 1.0
edge_weight: 0.5
centrality_weight: 0.5
2. Fallback auf Settings.RETRIEVER_W_* (ENV-basiert).
"""
Query-Vektor bestimmen:
- Falls query_vector gesetzt: unverändert verwenden (Back-compat, Tests).
- Sonst, falls query gesetzt: serverseitig einbetten.
- Andernfalls: Fehler.
settings = get_settings()
sem = float(getattr(settings, "RETRIEVER_W_SEM", 1.0))
edge = float(getattr(settings, "RETRIEVER_W_EDGE", 0.0))
cent = float(getattr(settings, "RETRIEVER_W_CENT", 0.0))
# YAML-Override, falls konfiguriert
config_path = os.getenv("MINDNET_RETRIEVER_CONFIG", "config/retriever.yaml")
if yaml is None:
return sem, edge, cent
try:
if os.path.exists(config_path):
with open(config_path, "r", encoding="utf-8") as f:
data = yaml.safe_load(f) or {}
scoring = data.get("scoring", {}) or {}
sem = float(scoring.get("semantic_weight", sem))
edge = float(scoring.get("edge_weight", edge))
cent = float(scoring.get("centrality_weight", cent))
except Exception:
# Bei Fehlern in der YAML-Konfiguration defensiv auf Defaults zurückfallen
return sem, edge, cent
return sem, edge, cent
def _get_client_and_prefix() -> Tuple[Any, str]:
"""Liefert (QdrantClient, prefix) basierend auf QdrantConfig.from_env()."""
cfg = qdr.QdrantConfig.from_env()
client = qdr.get_client(cfg)
return client, cfg.prefix
def _get_query_vector(req: QueryRequest) -> List[float]:
"""
Liefert den Query-Vektor aus dem Request.
- Falls req.query_vector gesetzt ist, wird dieser unverändert genutzt.
- Andernfalls wird req.query über den Embedding-Service in einen Vektor
transformiert.
"""
if req.query_vector:
return req.query_vector
if req.query:
return embed_text(req.query)
raise ValueError("query_vector fehlt. Alternativ 'query' (Text) übergeben, wird serverseitig eingebettet.")
return list(req.query_vector)
if not req.query:
raise ValueError("QueryRequest benötigt entweder query oder query_vector")
settings = get_settings()
model_name = settings.MODEL_NAME
# Kompatibel mit Fakes in Unit-Tests (ohne model_name-Parameter)
try:
return ec.embed_text(req.query, model_name=model_name) # type: ignore[call-arg]
except TypeError:
# Fallback: einfache Signatur embed_text(text)
return ec.embed_text(req.query) # type: ignore[call-arg]
def _semantic_hits(
client: Any,
prefix: str,
vector: List[float],
top_k: int,
filters: Dict[str, Any] | None = None,
) -> List[Tuple[str, float, Dict[str, Any]]]:
"""Führt eine semantische Suche über mindnet_chunks aus und liefert Roh-Treffer.
Rückgabeformat: Liste von (point_id, score, payload)
Erwartetes Format von qp.search_chunks_by_vector:
List[Tuple[str, float, dict]]
"""
flt = filters or None
raw_hits = qp.search_chunks_by_vector(client, prefix, vector, top=top_k, filters=flt)
results: List[Tuple[str, float, Dict[str, Any]]] = []
for pid, score, payload in raw_hits:
results.append((str(pid), float(score), dict(payload or {})))
return results
def _get_semantic_score_and_payload(
hit: Tuple[str, float, Dict[str, Any]]
) -> Tuple[float, Dict[str, Any]]:
"""Extrahiert semantic_score und Payload aus einem Raw-Hit."""
_, score, payload = hit
return float(score), payload or {}
def _compute_total_score(
semantic_score: float,
payload: Dict[str, Any],
edge_bonus: float = 0.0,
cent_bonus: float = 0.0,
) -> Tuple[float, float, float]:
"""Berechnet total_score aus semantic_score, retriever_weight und Graph-Boni.
Formel (WP-04, konfigurierbar über config/retriever.yaml bzw. ENV):
total_score = W_sem * semantic_score * max(retriever_weight, 0.0)
+ W_edge * edge_bonus
+ W_cent * cent_bonus
- retriever_weight stammt aus dem Chunk-Payload (types.yaml).
- W_sem / W_edge / W_cent kommen aus _get_scoring_weights().
"""
raw_weight = payload.get("retriever_weight", 1.0)
try:
weight = float(raw_weight)
except (TypeError, ValueError):
weight = 1.0
if weight < 0.0:
weight = 0.0
sem_w, edge_w, cent_w = _get_scoring_weights()
total = (sem_w * float(semantic_score) * weight) + (edge_w * edge_bonus) + (cent_w * cent_bonus)
return float(total), float(edge_bonus), float(cent_bonus)
def _extract_expand_options(req: QueryRequest) -> Tuple[int, List[str] | None]:
"""Extrahiert depth und edge_types aus req.expand, falls vorhanden.
- Falls expand nicht gesetzt ist: depth=0, edge_types=None (keine Expansion).
- Unterstützt sowohl Pydantic-Modelle als auch plain dicts.
"""
expand = getattr(req, "expand", None)
if not expand:
return 0, None
depth = 1
edge_types: List[str] | None = None
# Pydantic-Modell oder Objekt mit Attributen
if hasattr(expand, "depth") or hasattr(expand, "edge_types"):
depth = int(getattr(expand, "depth", 1) or 1)
types_val = getattr(expand, "edge_types", None)
if types_val:
edge_types = list(types_val)
return depth, edge_types
# Plain dict
if isinstance(expand, dict):
if "depth" in expand:
depth = int(expand.get("depth") or 1)
if "edge_types" in expand and expand["edge_types"] is not None:
edge_types = list(expand["edge_types"])
return depth, edge_types
return 0, None
def _build_hits_from_semantic(
hits: Iterable[Tuple[str, float, Dict[str, Any]]],
top_k: int,
used_mode: str,
subgraph: ga.Subgraph | None = None,
) -> QueryResponse:
"""Baut aus Raw-Hits und optionalem Subgraph strukturierte QueryHits.
- Aggregation auf Note-Ebene (note_id),
- Berechnung von total_score unter Nutzung von retriever_weight + Graph-Boni,
- Rückgabe als QueryResponse mit Latenz.
"""
t0 = time.time()
enriched: List[Tuple[str, float, Dict[str, Any], float, float, float]] = []
for pid, semantic_score, payload in hits:
# Graph-Scores, falls Subgraph und stabiler Key vorhanden
edge_bonus = 0.0
cent_bonus = 0.0
if subgraph is not None:
node_key = payload.get("chunk_id") or payload.get("note_id")
if node_key:
try:
edge_bonus = float(subgraph.edge_bonus(node_key))
except Exception:
edge_bonus = 0.0
try:
cent_bonus = float(subgraph.centrality_bonus(node_key))
except Exception:
cent_bonus = 0.0
total, edge_bonus, cent_bonus = _compute_total_score(
semantic_score,
payload,
edge_bonus=edge_bonus,
cent_bonus=cent_bonus,
)
enriched.append((pid, float(semantic_score), payload, total, edge_bonus, cent_bonus))
# Sortierung nach total_score absteigend
enriched_sorted = sorted(enriched, key=lambda h: h[3], reverse=True)
limited = enriched_sorted[: max(1, top_k)]
results: List[QueryHit] = []
for pid, semantic_score, payload, total, edge_bonus, cent_bonus in limited:
note_id = payload.get("note_id")
path = payload.get("path")
# mindnet_chunks: section (aktuell genutzt); ältere Stände nutzen ggf. section_title
section = payload.get("section") or payload.get("section_title")
results.append(
QueryHit(
node_id=str(pid),
note_id=note_id,
semantic_score=float(semantic_score),
edge_bonus=edge_bonus,
centrality_bonus=cent_bonus,
total_score=total,
paths=None,
source={
"path": path,
"section": section,
},
)
)
dt = int((time.time() - t0) * 1000)
return QueryResponse(results=results, used_mode=used_mode, latency_ms=dt)
def semantic_retrieve(req: QueryRequest) -> QueryResponse:
"""Nur semantische Kandidaten, keine Edge-Expansion (depth=0)."""
t0 = time.time()
s = get_settings()
client = QdrantClient(url=s.QDRANT_URL, api_key=s.QDRANT_API_KEY)
"""Reiner semantischer Retriever (ohne Edge-Expansion)."""
client, prefix = _get_client_and_prefix()
vector = _get_query_vector(req)
top_k = req.top_k or get_settings().RETRIEVER_TOP_K
q_vec = _vector_from_request(req)
raw_hits = qp.search_chunks_by_vector(client, s.COLLECTION_PREFIX, q_vec, top=req.top_k, filters=req.filters)
results: List[QueryHit] = []
for pid, s_score, payload in raw_hits:
results.append(QueryHit(
node_id=pid,
note_id=payload.get("note_id"),
semantic_score=float(s_score),
edge_bonus=0.0,
centrality_bonus=0.0,
total_score=float(s_score), # un-normalisiert: ok für quick semantic mode
paths=None,
source={"path": payload.get("path"), "section": payload.get("section_title")}
))
dt = int((time.time() - t0) * 1000)
return QueryResponse(results=results, used_mode="semantic", latency_ms=dt)
hits = _semantic_hits(client, prefix, vector, top_k=top_k, filters=req.filters)
return _build_hits_from_semantic(hits, top_k=top_k, used_mode="semantic", subgraph=None)
def hybrid_retrieve(req: QueryRequest) -> QueryResponse:
"""Semantik + Edge-Expansion + kombiniertes Ranking."""
t0 = time.time()
s = get_settings()
client = QdrantClient(url=s.QDRANT_URL, api_key=s.QDRANT_API_KEY)
"""Hybrid-Retriever: semantische Suche + optionale Edge-Expansion.
q_vec = _vector_from_request(req)
Aktueller Stand (Step 3):
- Semantische Suche über mindnet_chunks (wie semantic_retrieve),
- Bei expand.depth > 0 wird ein Subgraph aus mindnet_edges aufgebaut,
und edge_bonus / centrality_bonus in das Scoring einbezogen.
"""
client, prefix = _get_client_and_prefix()
# 1) Semantische Seeds (top_k * 3 für breitere Basis)
raw_hits = qp.search_chunks_by_vector(client, s.COLLECTION_PREFIX, q_vec, top=req.top_k * 3, filters=req.filters)
id2payload = {pid: payload for (pid, _, payload) in raw_hits}
seeds = [pid for (pid, _, _) in raw_hits]
# Query-Vektor:
# - Falls explizit gesetzt, unverändert nutzen.
# - Andernfalls über embed_text erzeugen.
if req.query_vector:
vector = list(req.query_vector)
else:
vector = _get_query_vector(req)
# 2) Edge-Expansion
edge_types = req.expand.get("edge_types") if req.expand else None
depth = req.expand.get("depth", 1) if req.expand else 1
sg = expand(client, s.COLLECTION_PREFIX, seeds, depth=depth, edge_types=edge_types)
top_k = req.top_k or get_settings().RETRIEVER_TOP_K
edge_bonus_map = {pid: sg.aggregate_edge_bonus(pid) for pid in seeds}
centrality_map = {pid: sg.centrality_bonus(pid) for pid in seeds}
hits = _semantic_hits(client, prefix, vector, top_k=top_k, filters=req.filters)
# 3) Combined Ranking
scored = combine_scores(
raw_hits, edge_bonus_map, centrality_map,
w_sem=s.RETRIEVER_W_SEM, w_edge=s.RETRIEVER_W_EDGE, w_cent=s.RETRIEVER_W_CENT
)
depth, edge_types = _extract_expand_options(req)
subgraph: ga.Subgraph | None = None
if depth and depth > 0:
# Seeds: stabile IDs aus dem Payload (chunk_id bevorzugt, sonst note_id)
seed_ids: List[str] = []
for _pid, _score, payload in hits:
key = payload.get("chunk_id") or payload.get("note_id")
if key and key not in seed_ids:
seed_ids.append(key)
# 4) Antwortobjekte (Chunk-Ebene)
results: List[QueryHit] = []
for pid, total, e, c, s_score in scored[: req.top_k]:
payload = id2payload[pid]
results.append(QueryHit(
node_id=pid,
note_id=payload.get("note_id"),
semantic_score=float(s_score),
edge_bonus=float(e),
centrality_bonus=float(c),
total_score=float(total),
paths=None,
source={"path": payload.get("path"), "section": payload.get("section_title")}
))
if seed_ids:
try:
subgraph = ga.expand(client, prefix, seed_ids, depth=depth, edge_types=edge_types)
except Exception:
# Edge-Expansion ist optional: bei Fehlern weiter ohne Graph-Boni
subgraph = None
dt = int((time.time() - t0) * 1000)
return QueryResponse(results=results, used_mode="hybrid", latency_ms=dt)
return _build_hits_from_semantic(hits, top_k=top_k, used_mode="hybrid", subgraph=subgraph)
+116
View File
@@ -0,0 +1,116 @@
"""app/core/retriever_config.py
---------------------------------
Zentrale Konfiguration für den mindnet-Retriever (WP-04).
Zweck:
- Lädt config/retriever.yaml (falls vorhanden) oder nutzt sinnvolle Defaults.
- Bietet einen gecachten Zugriff auf die Retriever-Config für
andere Module (z. B. graph_adapter, retriever).
Hinweis zur Weiterentwicklung (Selbstjustierung):
- Die hier definierten Parameter sind so gewählt, dass sie später
durch ein Feedback-/Learning-to-Rank-Modell überschrieben werden
können, ohne die restliche Architektur anzupassen.
"""
from __future__ import annotations
import os
from dataclasses import dataclass
from functools import lru_cache
from pathlib import Path
from typing import Dict
try:
import yaml # type: ignore
except Exception: # pragma: no cover - Fallback, falls PyYAML nicht installiert ist.
yaml = None # type: ignore
@dataclass(frozen=True)
class RetrieverConfig:
semantic_scale: float
edge_scale: float
centrality_scale: float
edge_weights: Dict[str, float]
@lru_cache
def get_retriever_config() -> RetrieverConfig:
"""Lädt die Retriever-Konfiguration (YAML + Defaults).
Reihenfolge:
1. Defaults (sinnvoll gewählte Startwerte).
2. Optional: config/retriever.yaml bzw. Pfad aus ENV
MINDNET_RETRIEVER_CONFIG überschreibt die Defaults.
Die Funktion ist bewusst gecached, da sich die Konfiguration zur
Laufzeit üblicherweise nicht ändert. Für dynamisches Nachladen
könnte der Cache explizit geleert werden.
"""
# 1) Defaults – bewusst konservativ gewählt.
semantic_scale = 1.0
edge_scale = 1.0
centrality_scale = 1.0
edge_weights: Dict[str, float] = {
# Wissens-Kanten
"depends_on": 1.0,
"related_to": 0.7,
"similar_to": 0.7,
"references": 0.5,
# Struktur-Kanten
"belongs_to": 0.2,
"next": 0.1,
"prev": 0.1,
# Sonstige / technische Kanten
"backlink": 0.2,
"references_at": 0.2,
}
# 2) Optional: YAML-Konfiguration laden
cfg_path_env = os.getenv("MINDNET_RETRIEVER_CONFIG")
if cfg_path_env:
cfg_path = Path(cfg_path_env)
else:
# Project-Root = zwei Ebenen über app/core/
cfg_path = Path(__file__).resolve().parents[2] / "config" / "retriever.yaml"
if yaml is not None and cfg_path.exists():
try:
data = yaml.safe_load(cfg_path.read_text(encoding="utf-8")) or {}
except Exception:
data = {}
retr = data.get("retriever") or {}
# Skalenwerte überschreiben, falls angegeben
try:
semantic_scale = float(retr.get("semantic_scale", semantic_scale))
except (TypeError, ValueError):
pass
try:
edge_scale = float(retr.get("edge_scale", edge_scale))
except (TypeError, ValueError):
pass
try:
centrality_scale = float(retr.get("centrality_scale", centrality_scale))
except (TypeError, ValueError):
pass
# Edge-Gewichte je Kanten-Typ
ew_cfg = retr.get("edge_weights") or {}
if isinstance(ew_cfg, dict):
for k, v in ew_cfg.items():
try:
edge_weights[str(k)] = float(v)
except (TypeError, ValueError):
continue
return RetrieverConfig(
semantic_scale=semantic_scale,
edge_scale=edge_scale,
centrality_scale=centrality_scale,
edge_weights=edge_weights,
)
+24
View File
@@ -0,0 +1,24 @@
version: 1.0
scoring:
# W_sem: skaliert den Term (semantic_score * retriever_weight)
# Empfehlung Startwert: 1.0 → Semantik bleibt Hauptsignal
semantic_weight: 1.0
# W_edge: skaliert edge_bonus aus dem Subgraph
# Empfehlung: 0.7 → Graph ist deutlich spürbar, aber überstimmt Semantik nicht komplett
edge_weight: 0.7
# W_cent: skaliert centrality_bonus (Knoten-Zentralität im Subgraph)
# Empfehlung: 0.5 → zentrale Knoten werden bevorzugt, aber moderat
centrality_weight: 0.5
# Optional, für später (aktuell noch nicht ausgewertet, aber als Blaupause):
edge_types:
references: 0.20
depends_on: 0.18
related_to: 0.15
similar_to: 0.12
belongs_to: 0.10
next: 0.06
prev: 0.06
+64 -13
View File
@@ -1,25 +1,76 @@
version: 1.0
defaults:
retriever_weight: 0.1
retriever_weight: 1.0
chunk_profile: default
edge_defaults: [] # Leerliste → keine impliziten Kanten, wenn nicht gesetzt
types:
# Wissensbausteine
concept:
chunk_profile: medium
retriever_weight: 0.60
edge_defaults: ["references", "related_to"]
retriever_weight: 0.35
task:
source:
chunk_profile: short
edge_defaults: ["depends_on", "belongs_to"]
retriever_weight: 0.8
experience:
retriever_weight: 0.50
edge_defaults: [] # Quellen sind i. d. R. Ziel von Kanten, erzeugen selbst keine Default-Kanten
glossary:
chunk_profile: short
retriever_weight: 0.40
edge_defaults: ["related_to"]
# Person & Persönlichkeit
profile: # z. B. "Persönliches Leitbild (Kurzprofil)"
chunk_profile: long
retriever_weight: 0.66
edge_defaults: ["references", "related_to"]
value: # Werte (z. B. "Mut", "Fairness")
chunk_profile: short
retriever_weight: 0.90
edge_defaults: ["related_to"]
principle: # Prinzipien/Leitsätze
chunk_profile: short
retriever_weight: 0.90
edge_defaults: ["related_to", "references"]
experience: # prägende Erlebnisse/Erfahrungen
chunk_profile: medium
edge_defaults: ["derived_from", "inspired_by"]
retriever_weight: 0.9
retriever_weight: 0.90
edge_defaults: ["related_to", "references"]
# Ziele, Entscheidungen, Meilensteine
goal:
chunk_profile: medium
retriever_weight: 0.90
edge_defaults: ["depends_on", "related_to", "references"]
decision:
chunk_profile: short
retriever_weight: 0.90
edge_defaults: ["depends_on", "references", "related_to"] # „Worauf stützte sich die Entscheidung?“
milestone:
chunk_profile: short
retriever_weight: 0.70
edge_defaults: ["related_to", "references"]
# Operativ: Projekte, Aufgaben, Journal
project:
chunk_profile: long
edge_defaults: ["references", "depends_on"]
retriever_weight: 0.97
profile:
chunk_profile: long
edge_defaults: ["references", "depends_on"]
retriever_weight: 0.66
edge_defaults: ["references", "depends_on"] # Projekt stützt sich auf Konzepte/Quellen und hängt von Bausteinen ab
task:
chunk_profile: short
retriever_weight: 0.80
edge_defaults: ["depends_on", "references"]
journal:
chunk_profile: medium
retriever_weight: 0.80
edge_defaults: ["references", "related_to"]
+96
View File
@@ -0,0 +1,96 @@
# mindnet Retriever (WP-04 / Step 4a) – Kurz-Dokumentation
## 1. Überblick
Der Retriever besteht aus:
- **Semantic Retriever** (`semantic_retrieve`)
- **Hybrid Retriever** (`hybrid_retrieve`)
- Qdrant-Backend (`*_chunks`, `*_edges`)
- optionaler Edge-Expansion über `graph_adapter.expand`
Die API nutzt das bestehende `/query`-Endpoint (FastAPI), das `QueryRequest` und `QueryResponse` aus `app.models.dto` verwendet.
## 2. Scoring-Formel
Pro Treffer werden folgende Komponenten geführt:
- `semantic_score` – direkt aus Qdrant (Cosine/Euclidean, je nach Collection)
- `retriever_weight` – aus Chunk-Payload (`types.yaml` / Frontmatter)
- `edge_bonus` – Bonus aus dem Subgraph (z. B. Zahl der eingehenden/ausgehenden Edges, Beziehungstypen)
- `centrality_bonus` – Bonus aus einer einfachen Zentralitäts-Heuristik im Subgraph
Aktuelle Formel (Step 4a):
```text
total_score = semantic_score * max(retriever_weight, 0.0)
+ edge_bonus
+ centrality_bonus
```
Die Sortierung der Ergebnisse erfolgt absteigend nach `total_score`.
## 3. Modi
### 3.1 Semantic Mode
- Funktion: `semantic_retrieve`
- Request-Feld `mode = "semantic"`
- Keine Edge-Expansion, kein Graph-Call.
- Kandidaten nur aus Vektorsuche in `<prefix>_chunks`.
### 3.2 Hybrid Mode
- Funktion: `hybrid_retrieve`
- Request-Feld `mode = "hybrid"`
- Schritte:
1. Semantische Chunk-Suche wie im Semantic Mode
2. Falls `expand.depth > 0` gesetzt ist:
- Seeds = `chunk_id` (Fallback: `note_id`) der Treffer
- Aufruf `graph_adapter.expand(client, prefix, seed_ids, depth, edge_types)`
- Ergebnis-Subgraph liefert `edge_bonus` und `centrality_bonus` pro Node
3. Scores werden nach obiger Formel kombiniert.
## 4. Request-Struktur (JSON)
Beispiel-Hybrid-Request:
```json
{
"mode": "hybrid",
"query": "embeddings und qdrant",
"top_k": 10,
"expand": {
"depth": 1,
"edge_types": ["references", "depends_on"]
}
}
```
Minimaler Semantic-Request:
```json
{
"mode": "semantic",
"query": "karate trainingsplan",
"top_k": 5
}
```
## 5. Smoke-Test
Für einen schnellen End-to-End-Test kann folgendes Skript verwendet werden:
```bash
python scripts/test_retriever_smoke.py --query "karate" --mode hybrid --expand-depth 1 --top-k 5
```
Das Skript ruft `/query` auf, wertet Statuscode und JSON-Antwort aus und zeigt die Scores der Top-K-Treffer an.
## 6. Tests
Die wichtigsten Tests für den Retriever sind:
- `tests/test_retriever_basic.py` – Basisfunktion (Semantic + Hybrid)
- `tests/test_retriever_weight.py` – Einfluss von `retriever_weight` auf das Ranking
- `tests/test_retriever_edges.py` – Einfluss von Edge-/Centrality-Boni im Hybrid-Modus
+245 -146
View File
@@ -1,192 +1,291 @@
# Mindnet – Fachliche Architektur
**Version:** 2.0 • **Datum:** 2025-11-09 • **Autor:** Fachkonzept (gemeinsam mit Owner)
# Mindnet – Fachliche Architektur (Stand: 2025-11-17)
> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten) zwischen Notizen/Chunks. Die technische Umsetzung (Module, Flags, Schemas) wird nur dort angerissen, wo es zum Verständnis nötig ist und im technischen Dokument detailliert.
---
## 0. Zweck dieses Dokuments
Dieses Dokument beschreibt **Fachdomäne, Funktionsräume, Prozesse und Regeln** von *mindnet*. Es ergänzt die technische Architektur und macht die ursprünglichen Ziele, Designentscheidungen, Anti‑Patterns und Umsetzungsstrategien explizit nachvollziehbar.
## 0) Zielbild & Grundprinzip
Mindnet wandelt Obsidian-Markdown-Notizen in einen **Graph aus Punkten und Kanten** um.
Die drei zentralen Artefakt-Sammlungen lauten:
- `mindnet_notes` – genau **eine** Note pro Markdown-Datei (Metadaten & Hashes)
- `mindnet_chunks` – semantische Teilstücke einer Note (Fenster/„Chunks“)
- `mindnet_edges` – gerichtete Beziehungen zwischen Knoten (Chunks/Notes)
Die Import-Pipeline erzeugt diese Artefakte **deterministisch** und **idempotent** (erneute Läufe überschreiben konsistent statt zu duplizieren). Die Import-Schritte sind: *parse → chunk → edge → upsert*. :contentReference[oaicite:0]{index=0}
---
## 1. Vision & Leitplanken
- **Essenz bewahren:** Entscheidungen, Erlebnisse, Werte, Prinzipien und Konditionierungen so strukturieren, dass sie später erklärbar rekonstruiert werden können.
- **Antworten im eigenen Stil:** Ergebnisse sollen die Persönlichkeit des Owners widerspiegeln (Sprache: **Deutsch**).
- **Vertraulichkeit:** Aktuell einheitlich, aber mit **Stufen** (public/internal/sensitive) erweiterbar.
- **Zeitliche Priorisierung:** Standard: jüngere Inhalte leichter gewichten; Ausnahmen konfigurierbar.
- **Lokal zuerst**, später skalierbar.
## 1) Notizen & Chunks (fachliche Perspektive)
### 1.1 Notiz (Note)
- Repräsentiert eine fachliche Einheit (z. B. *„Vector DB Basics“*, *„KI-Projekt“*).
- Trägt Eigenschaften (Titel, Typ, Zeitstempel, optionale Policies).
- **Typ** (*type*) steuert u. a. Chunk-Profil und Default-Relationen (siehe §4).
- **retriever_weight** und **chunk_profile** werden systematisch an Note **und** Chunks gespiegelt, damit der Retriever beides nutzen kann. :contentReference[oaicite:1]{index=1}
### 1.2 Chunk
- Ausschnitt/Textfenster aus der Note, als eigenständiger Such-Anker.
- Jeder Chunk gehört **genau einer** Note.
- Chunks bilden eine Sequenz (1…N) – das ermöglicht *next/prev*.
> **Wichtig:** Chunking-Profile (short/medium/long) kommen aus `types.yaml` (per Note-Typ), können aber lokal überschrieben werden. Die effektiven Werte werden bei der Payload-Erzeugung bestimmt. :contentReference[oaicite:2]{index=2}
---
## 2. Fachliches Datenmodell
### 2.1 Kernobjekte
- **Note**: Eintrag im Wissensnetz (z. B. Konzept, Projekt, Erfahrung, Ereignis, Aufgabe).
- **Chunk**: semantischer Abschnitt einer Note (Antwortbaustein).
- **Edge**: gerichtete Beziehung zwischen Notes/Chunks (mit Typ, Gewicht, Quelle).
- **Run**: Importlauf (Audit).
- **Config**: aktive Regel‑ und Typkonfigurationen.
## 2) Edges – fachliche Typen & Bedeutung
### 2.2 Typen & Semantik (Auszug)
- `concept`: Begriff/These/Prinzip.
- `experience`: Erlebnis/Beobachtung (zeitlich verankert).
- `project`: Vorhaben mit Zielen/Abhängigkeiten.
- `task`: Arbeitseinheit.
- (erweiterbar: `event`, `decision`, `person`, `place`, `quote` …)
Edges kodieren Beziehungen. Sie sind **gerichtet** und werden in `mindnet_edges` gespeichert.
### 2.3 Relationen (fachlich)
- `references`: verweist inhaltlich auf …
- `related_to`: thematische Nähe/Assoziation.
- `depends_on`: fachliche/kausale Abhängigkeit.
- `belongs_to`: Zugehörigkeit (Teil‑von, Kapitel‑zu).
- `derived_from`: abgeleitet (z. B. Schluss aus Erfahrung).
- `inspired_by`: Impuls/Idee aus Quelle.
- `supports` / `contradicts`: argumentative Beziehung.
### 2.1 Struktur-Kanten
- **belongs_to**: *Chunk → Note* (Zuordnung)
- **next / prev**: Kettenbeziehungen zwischen aufeinanderfolgenden Chunks derselben Note
→ ermöglichen „lineares Weiterlesen“ oder Kontextpfade in Antworten.
Diese Kanten entstehen immer, unabhängig von Inhalten. :contentReference[oaicite:3]{index=3}
### 2.2 Inhalts-Kanten (explizit)
- **references (chunk-scope)**: aus dem Textfenster des Chunks extrahierte Links.
Standardquelle: **Wikilinks** `[[…]]` – einschließlich Varianten `[[id#anchor]]`, `[[id|label]]`.
→ Mindnet reduziert robust auf die Ziel-ID (Titel/ID-Normalisierung). :contentReference[oaicite:4]{index=4}
- **Explizite Inline-Relationen**: im Fließtext notierte Relationen, z. B.:
rel: similar_to [[Vector DB Basics]]
→ werden als Relation **similar_to** mit hoher Confidence materialisiert; *rule_id* `inline:rel`.
(Diese Form ist besonders kompakt in Obsidian editierbar.)
- **Callout-Edges** (optional):
> [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]]
→ erzeugt mehrere **related_to**-Kanten aus einer Zeile; *rule_id* `callout:edge`.
(Für kuratierte, sichtbare Linklisten am Notizende.)
> Alle expliziten Quellen (Wikilink, Inline-Rel, Callout) sind **gleichwertige Primärbelege** und werden als *provenance=explicit* geführt. Wo zutreffend, tragen Edges *rule_id* wie `explicit:wikilink`, `inline:rel`, `callout:edge`. :contentReference[oaicite:5]{index=5}
### 2.3 Typ-basierte Default-Kanten (regelbasiert)
Jede Note hat einen *Typ* (z. B. `concept`, `project`, `profile`). In `config/types.yaml` definieren wir pro Typ **edge_defaults**, z. B.:
- `concept`: `["references","related_to"]`
- `project`: `["references","depends_on"]`
Regel: **Für jede gefundene explizite Referenz** (s. o.) werden **zusätzliche** Edges nach diesen Defaults erzeugt. Beispiel: Ein *project* mit `edge_defaults=["depends_on"]` erzeugt zu *jedem* explizit referenzierten Ziel **zusätzlich** eine `depends_on`-Kante.
Diese Kanten tragen *provenance=rule* und eine **rule_id** der Form
`edge_defaults:{note_type}:{relation}` (z. B. `edge_defaults:project:depends_on`). :contentReference[oaicite:6]{index=6}
---
## 3. Funktionsräume
1. **Kurativer Raum**
- Schreiben/Überarbeiten von Notizen (Obsidian Templates, Frontmatter‑Guides).
- Plausibilisierung: Pflichtfelder, Dublettencheck, Warnungen (z. B. fehlende Relationen).
## 3) Edge-Payload – Felder & Semantik
2. **Graphischer Raum**
- Relationen setzen (declared), Vorschläge prüfen (inferred).
- Subgraph‑Explorer je Frage/Entscheidung.
Jede Kante hat mindestens:
3. **Antwort‑Raum**
- Query‑Typen: *Faktenabruf*, *Erlebnisbasiert erklären*, *Planung/Entscheidung begründen*.
- Erklärpfad: Chunks → Kanten → Zeitfaktoren → Typgewichte.
- `kind` – Beziehungsart *(belongs_to, next, prev, references, related_to, depends_on, similar_to, …)*
- `scope` – `"chunk"` (Standard) oder `"note"` (optional für Backlinks/Note-Scope)
- `source_id`, `target_id` – Quell-/Ziel-Knoten (Chunk- oder Note-ID)
- `note_id` – **Owner-Note** (die Note, aus der die Kante stammt; dient der schnellen Löschung/Filterung)
4. **Governance‑Raum**
- Sichtbarkeit/ACL, Qualitätsflags, Review‑Queues.
- Versionsjournal, Import‑Runs, Config‑Historie.
Erweiterte/abgeleitete Felder (V2-Superset):
- `provenance` – `"explicit"` (Wikilink/Inline/Callout) oder `"rule"` (Typ-Defaults)
- `rule_id` – maschinenlesbare Regelquelle, z. B.
- `explicit:wikilink`, `inline:rel`, `callout:edge`
- `edge_defaults:{note_type}:{relation}`
- `confidence` – 0.0–1.0; Heuristik, z. B. `1.0` für Wikilinks/Backlinks, `0.95` für `inline:rel`, `0.7` für Typ-Defaults.
**Dedup-Schlüssel** (fachlich): Gleichlautende `(source_id, target_id, kind, scope, rule_id)` werden nicht mehrfach geschrieben. :contentReference[oaicite:7]{index=7}
---
## 4. Fachliche Regeln
### 4.1 Frontmatter‑Schema (Mindeststandard)
```yaml
id: "{deterministic}"
title: "…"
type: "concept|experience|project|task|…"
created: "YYYY-MM-DD"
modified: "YYYY-MM-DD"
visibility: "internal" # default
retriever_weight: null # optional override
chunk_profile: null # optional override
tags: ["…"]
edge_hints:
- relation: references
target: "note-id-or-path"
- relation: depends_on
target: "…"
```
## 4) Typ-Registry (`config/types.yaml`)
### 4.2 Typregeln (aus types.yaml)
- `chunk_profile`, `retriever_weight`, `edge_defaults` werden je Typ **automatisch** angewandt.
- Aus `edge_defaults` abgeleitete Kanten werden **persistiert** (`source='rule'`).
### 4.1 Zweck
- Steuert **Chunking-Profile** (`short|medium|long`) **pro Typ**
- Liefert **retriever_weight** (Note-/Chunk-Gewichtung im Ranking) **pro Typ**
- Definiert **edge_defaults** je Typ (s. o.)
### 4.3 Zeitgewichtung
- Default: **Exponential Decay** mit globalem λ; Override per `time_weight_override` möglich.
- Erlebnisse (`experience`) erhalten standardmäßig leicht höheren **Base‑Impact** im Score, um Persönlichkeit abzubilden.
Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. **Frontmatter-Overrides** (z. B. `retriever_weight`) werden respektiert; am Ende schreibt der Importer die **effektiven** Werte zuverlässig in Note- und Chunk-Payload. :contentReference[oaicite:8]{index=8}
### 4.4 Qualitätsregeln
- Jede Note soll **mind. eine Relation** besitzen.
- **Konflikte** (contradicts) werden nicht gefiltert, sondern sichtbar gemacht (mit Hinweis).
- **Sichtbarkeit**: Antworten aus `sensitive` nur bei expliziter Freigabe.
### 4.2 Beispiel (auslieferungsnah)
version: 1.0
types:
concept:
chunk_profile: medium
edge_defaults: ["references", "related_to"]
retriever_weight: 0.35
project:
chunk_profile: long
edge_defaults: ["references", "depends_on"]
retriever_weight: 0.97
profile:
chunk_profile: long
edge_defaults: ["references", "depends_on"]
retriever_weight: 0.66
**Auflösung im Importer**
- `effective_chunk_profile(note_type, registry)` → `"short|medium|long"|None`
- `effective_retriever_weight(note_type, registry)` → `float|None`
- Ergebnis wird in `note_payload` **und** `chunk_payloads` gespiegelt. :contentReference[oaicite:9]{index=9}
---
## 5. Use Cases (repräsentativ)
1. **„Warum habe ich 2019 X entschieden?“**
- Abfrage auf `decision` + temporale Nachbarschaft zu `experience`/`principle`.
- Ausgabe mit Erklärpfad: *Erlebnis → Prinzip → Projekt → Entscheidung*.
## 5) Wie entstehen Edges aus Markdown?
2. **„Plane ein Trainingsprogramm“**
- Query kombiniert Konzepte/Erfahrungen/Projekte → Graph‑Walk + Typgewichtung, priorisiert jüngere Erkenntnisse.
### 5.1 Quelle „Wikilinks“ (Primärfall)
- Parser extrahiert alle `[[…]]` (Label/Anker werden auf die Ziel-ID reduziert).
- Pro Fund entsteht **eine** `references`-Kante (Chunk-Scope).
- Zusätzlich: Typ-Defaults (z. B. `depends_on`, `related_to`) pro Ziel. :contentReference[oaicite:10]{index=10}
3. **„Welche Ereignisse haben mein Leitbild geprägt?“**
- Subgraph über `derived_from`/`inspired_by` Ketten + Zeitachsen‑Visualisierung.
### 5.2 Quelle „Inline-Relation“ (Optional, kompakt)
- Im Fließtext markierte Relation, z. B.:
rel: similar_to [[Vector DB Basics]]
- Erzeugt `similar_to`-Kanten; *rule_id* `inline:rel`; `confidence≈0.95`.
- Geeignet für sparsame, gut lesbare Referenzierung. (Erfassung in der Chunk-Window-Analyse.) :contentReference[oaicite:11]{index=11}
### 5.3 Quelle „Callout-Edges“ (Optional, kuratiert)
- Klar sichtbare, redaktionell gepflegte Liste am Ende einer Note:
> [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]]
- Erzeugt je Ziel eine `related_to`-Kante; *rule_id* `callout:edge`.
- Eignet sich für „Leselisten“ und „Siehe auch“. (Zählung als *callout_total* in Reports, wo vorhanden.) :contentReference[oaicite:12]{index=12}
### 5.4 Struktur-Kanten
- `belongs_to` pro Chunk
- `next/prev` aus Nachbarbezug (aus Chunk-Sequenz/Neighbors) :contentReference[oaicite:13]{index=13}
> **Hinweis zu Note-Scope:** Optional können zusätzlich Note-weite *references/backlinks* aus der Gesamtheit aller Chunk-Funde abgeleitet werden (Konfig-Flag/ENV). Das ist für globale Graph-Analysen nützlich, aber im Retrieval seltener erforderlich. :contentReference[oaicite:14]{index=14}
---
## 6. Anti‑Patterns (vermeiden)
- **Edges ohne Relation** („Dot‑Kanten“) – verhindern jede sinnvolle Auswertung.
- **Nur Vektor‑Suche** ohne Graph / Zeitfaktor – verfälscht Persönlichkeit.
- **Freies Tag‑Chaos** ohne Typregeln – mindert Reproduzierbarkeit.
- **Heimliche Workarounds** (z. B. Felder mit Mehrdeutigkeit) – erschweren spätere Automatisierung.
## 6) Confidence & Provenance – wozu?
Der Retriever kann Edges gewichten:
- **provenance**: *explicit* > *rule*
- **confidence**: numerische Feinsteuerung (z. B. Inline-Relation etwas höher, Defaults etwas niedriger)
- **retriever_weight (Note/Chunk)**: skaliert die Relevanz des gesamten Knotens
Eine typische Gewichtung (konfigurierbar) ist:
explicit: 1.0, rule: 0.8, default_resolved: 0.6, default: 0.2
Damit bevorzugt der Graph **kuratiertes Wissen** (explizit notierte Links) vor „erweiterten“ Default-Ableitungen. :contentReference[oaicite:15]{index=15}
---
## 7. Umsetzungsstrategie & Roadmap
### Phase 1 (Jetzt)
- Pflicht‑Frontmatter, deterministische IDs, Ingestion v2 (Chunks/Edges **persistiert**).
- types.yaml + retrieval.yaml live‑fähig; Import‑Run‑Audit.
- Tests (Parser/Chunker/Edge‑Rules), Regression auf Chunk‑Mengen.
## 7) Semantik ausgewählter `kind`-Werte
### Phase 2
- Hybrid‑Retrieval mit Graph‑Boosts, Explain‑Traces in API.
- Subgraph‑Explorer, Governance‑Views (Review‑Queues).
- `references` – „Nutzt/erwähnt“; neutral, aber stützend für Kontext.
- `related_to` – Ähnlichkeit/Verwandtschaft (symmetrisch interpretierbar).
- `similar_to` – noch engere Ähnlichkeit; oft aus Inline-Rel (bewusst gesetzt).
- `depends_on` – fachliche Abhängigkeit (z. B. „Projekt X hängt von Y ab“).
- `belongs_to`, `next`, `prev` – Struktur.
### Phase 3
- ML‑gestützte Edge‑Vorschläge, temporale Graphanalysen, Reasoning‑Chains.
- ACL/Sharing‑Modelle, Export/Archiv‑Pipelines.
> Symmetrische Relationen (z. B. `related_to`, `similar_to`) können **explizit** nur einseitig notiert sein, aber im Retriever beidseitig interpretiert werden (z. B. Query-Zeit-Expansion), um Redundanz im Vault zu vermeiden. :contentReference[oaicite:16]{index=16}
---
## 8. Beispiel‑Konfigurationen
### 8.1 types.yaml (Beispiel – wie technisch)
```yaml
version: 1.0
types:
concept:
chunk_profile: medium
edge_defaults: ["references", "related_to"]
retriever_weight: 0.33
task:
chunk_profile: short
edge_defaults: ["depends_on", "belongs_to"]
retriever_weight: 0.8
experience:
chunk_profile: medium
edge_defaults: ["derived_from", "inspired_by"]
retriever_weight: 0.9
project:
chunk_profile: long
edge_defaults: ["references", "depends_on"]
retriever_weight: 0.95
```
## 8) Frontmatter-Eigenschaften – Rolle & Empfehlung
### 8.2 retrieval.yaml
```yaml
relation_weights:
references: 1.0
related_to: 0.6
depends_on: 1.2
belongs_to: 0.8
derived_from: 1.1
inspired_by: 0.8
supports: 1.0
contradicts: -0.9
mixing:
alpha: 0.45
beta: 0.25
gamma: 0.20
delta: 0.07
epsilon: 0.03
time_decay:
lambda: 0.0025
```
Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
- **type** – steuert Typ-Defaults via Registry (Pflicht für differenziertes Verhalten).
- **retriever_weight** *(optional)* – kann typbasierte Defaults überschreiben.
- **chunk_profile** *(optional)* – kann typbasierte Defaults überschreiben.
- **links** *(optional, Bestandskompatibilität)* – wenn vorhanden (z. B. `depends_on: …`), können sie als explizite Kanten materialisiert werden; die Pflege in freiem Text (Inline/Callout) ist jedoch **benutzerfreundlicher** und weniger fehleranfällig.
Empfehlung: **Links primär über Text (Wikilink/Inline/Callout) pflegen**, nicht als Properties. Die Registry regelt Standards; Properties dienen nur gezielten Ausnahmen. :contentReference[oaicite:17]{index=17}
---
## 9. Governance & Nachvollziehbarkeit
- **Decision Log** (ADR‑ähnlich): jedes Regel‑/Schema‑Update mit Begründung.
- **Import‑Protokolle** versioniert, inkl. geänderter Dateien, Chunk‑/Edge‑Zahlen.
- **Explainability Standard** in jeder Antwort.
## 9) Lösch-/Update-Garantien (Idempotenz)
- Jede Note hat einen stabilen **note_id** (Frontmatter/Hash).
- Vor einem Upsert können *alte Chunks/Edges einer Note* gefiltert gelöscht werden (`note_id`-Filter) – das hält Collections sauber bei Re-Imports.
- Es gibt Abkürzungen für „fehlertolerante Rebuilds“: *Existenz-Checks* statt Full-Scan. :contentReference[oaicite:18]{index=18}
---
## Anhang A: Glossar
- **Chunk‑Profil**: Regelset zur Textteilung.
- **Rule‑Edge**: automatisch erzeugte Kante auf Basis von Typregeln.
- **Declared Edge**: explizit gesetzte Kante aus der Quelle.
## 10) Beispiel – Von Markdown zu Kanten
**Markdown (Auszug)**
# Relations Showcase
…
rel: similar_to [[Vector DB Basics]]
…
[[Embeddings 101]]
> [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]]
**Ergebnis (fachlich)**
- `references(Chunk→Vector DB Basics)` + `references(Chunk→Embeddings 101)`
- `similar_to(Chunk→Vector DB Basics)` mit `rule_id=inline:rel`, `confidence≈0.95`
- `related_to(Chunk→Vector DB Basics)` und `related_to(Chunk→Embeddings 101)`
via Callout; `rule_id=callout:edge`
- Zusätzliche **Typ-Defaults** je Quell-Typ, z. B. `edge_defaults:concept:related_to` → weitere `related_to`-Kanten
*Strukturkanten* (`belongs_to`, `next/prev`) fallen wie üblich an. (Die tatsächlichen Zähllogiken erscheinen im Import-Report/Smoke-Tests.) :contentReference[oaicite:19]{index=19}
---
## 11) Abfrage-Implikationen (fachlich)
Retriever und Query-Layer berücksichtigen:
1) **Knoten-Gewicht** (`retriever_weight`) aus Typ/Property (Note & Chunk).
2) **Edge-Provenance/Confidence** – explizit > regelbasiert; höhere Confidence bevorzugt.
3) **Edge-Topologie** – z. B. 1-Hop-Nachbarschaft, Sequenzpfade (`next/prev`), Backlinks (optional).
4) **Policy-Filter** – Privacy, Tags, Created usw. via Payload-Indizes.
Die Abfrage kann so z. B. Ergebnisse bevorzugen, die **explizit** in einem *Projekt* als `depends_on` genannt sind – und nur nachrangig solche, die „typbedingt“ (`edge_defaults`) ähnlich/abhängig sind. :contentReference[oaicite:20]{index=20}
---
## 12) Qualitäts- und Testkriterien (fachlich)
- **Keine Duplikate** gleicher `(src, relation, dst)` in der Collectionsicht (Dedup).
- **Explizite Links** werden vollständig materialisiert (*explicit_total*).
- **Typ-Defaults** ergänzen, aber überdecken nicht – Counts bleiben plausibel (*defaults_total*).
- **Inline/Callout** werden separat quantifiziert (*inline_total*, *callout_total*), damit Redaktionen ihre Pflegewirkung beobachten können. :contentReference[oaicite:21]{index=21}
---
## 13) Praxisempfehlungen für den Vault
1) **Wikilinks** überall, wo eine inhaltliche Nennung stattfindet.
2) Für **gezielte Relationen** (Ähnlichkeit/Abhängigkeit) kurze **Inline-Rel**-Zeilen; z. B.:
rel: similar_to [[X]]
rel: related_to [[Y]] [[Z]]
3) Am Notizende **Callout-Edges** für kuratierte Überblicksblöcke:
> [!edge] related_to: [[X]] [[Y]]
4) **Properties** schlank halten: mindestens `type`, optional `retriever_weight`/`chunk_profile`.
5) **types.yaml** pflegen (zentrale Governance): *Welche Typen gibt es? Welche Default-Relationen sind fachlich sinnvoll?*
6) **Regelmäßige Smoke-Tests/Reports** prüfen die Kanten-Counts und Provenance-Verteilung. :contentReference[oaicite:22]{index=22}
---
## 14) Referenzen (Projektdateien & Leitlinien)
- Import-Pipeline & Registry-Auflösung (Importer, Flags, Idempotenz): `scripts/import_markdown.py`. :contentReference[oaicite:23]{index=23}
- Robuste Kantenbildung (Wikilinks, Struktur, optionale Note-Scope): `app/core/derive_edges.py` (v1.4+). :contentReference[oaicite:24]{index=24}
- V2-Edge-Superset (Provenance, rule_id, Confidence, Typ-Defaults): `app/core/edges.py` (v2.0+). :contentReference[oaicite:25]{index=25}
- Typ-Registry laden/auflösen (Fallbacks, Effektivwerte): Import-Helper / *Type-Registry*-Hilfsfunktionen. :contentReference[oaicite:26]{index=26}
- Test-/Playbook-Leitplanken (Policies, KPIs, Roadmap): *Implementation Playbook*. :contentReference[oaicite:27]{index=27}
---
## 15) Anhang – Mini-Beispiel einer Projekt-Note (verkürzt)
---
id: 20251110-ki-trainerassistent-projekt-56d2aa
title: KI Trainerassistent (Projekt)
type: project
retriever_weight: 1.0 # optional Override
chunk_profile: default # optional Override
---
# KI Trainerassistent (Projekt)
Wir nutzen [[Qdrant Vektordatenbank]] und [[Ollama LLM]] …
rel: depends_on [[Qdrant Vektordatenbank]]
rel: related_to [[Ollama LLM]]
> [!edge] depends_on: [[Qdrant Vektordatenbank]]
> [!edge] related_to: [[Ollama LLM]]
*Erwartung*:
- `references` (Wikilinks) auf **beide** Ziele
- `depends_on` & `related_to` via **Inline** und **Callout** (provenance=`explicit`, rule_id `inline:rel`/`callout:edge`)
- Zusätzlich **Typ-Defaults** aus `types.yaml` für `project` (z. B. weitere `depends_on`) – provenance=`rule`, `rule_id=edge_defaults:project:depends_on`. :contentReference[oaicite:28]{index=28}
---
File diff suppressed because it is too large. Load diff
+42 -1
View File
@@ -19,6 +19,31 @@
> **Warum so?** Qdrant‑Payload‑Indizes/Filter → schnelle, erklärbare Selektionen; Snapshots → betriebssicheres Rollback; OTel → Nachvollziehbarkeit; YAML/JSON‑Schema → Validierbarkeit & Stabilität.
### 0.1 Aktueller Implementierungsstand (2025-11-18)
- Es existiert eine produktive mindnet-Instanz mit den Collections:
- `${prefix}_notes`
- `${prefix}_chunks`
- `${prefix}_edges`
- Import-Pipeline:
- `scripts/import_markdown.py` erzeugt Notes, Chunks und Edges vollständig.
- `types.yaml` definiert per Note-Typ:
- `retriever_weight`
- `chunk_profile`
- `edge_defaults` (z. B. `depends_on`, `related_to`).
- Edges:
- Strukturkanten: `belongs_to`, `next`, `prev`
- Explizite Kanten aus Wikilinks: `kind="references"`, `rule_id="explicit:wikilink"`
- Typbasierte Default-Kanten aus `edge_defaults`: `rule_id="edge_defaults:<type>:<relation>"`
- Inline-Kanten im Format `[[rel:<relation> <Zielnote>]]` mit `rule_id="inline:rel"`
- alle Edges tragen eine `confidence` im Bereich `[0,1]` als Hinweis für spätere Ranking-Logiken.
- Tests:
- `tests/test_edges_smoke.py`, `tests/test_edges_all.py` und `scripts/edges_full_check.py` validieren Counts, Konsistenz (`belongs_to == chunks`, `next/prev`-Ketten, keine Duplikate) und Provenienz-Zählungen (`explicit`, `defaults`, `inline`, `structure`).
- Offene Punkte:
- Mehrere Ziele in einer Inline-Relation (`rel: similar_to [[A]] [[B]]`) sind noch nicht implementiert.
- Retrieval-Service nutzt die neuen Edges und Weights bisher nur teilweise; ein edge-bewusster Retriever ist als nächster Schritt geplant.
---
## 1) Datenmodelle (Schemata, v2)
@@ -196,10 +221,15 @@ rule_sets:
- CI‑Job: `make schema-validate` (jsonschema).
- **Abnahme:** Validator grün auf 3 Gold‑Notizen.
### Step 2 – Qdrant v2‑Collections
### Step 2 – Qdrant v2‑Collections (Optional)
- Anlegen der 3 v2‑Collections + Payload‑Indizes.
- **Abnahme:** Filter‑Query liefert erwartbare Ergebnisse.
### Step 2a – Edge-Pipeline v1 stabilisieren (ERLEDIGT)
- Ziel: Vollständige Generierung von Struktur-, expliziten, typbasierten und Inline-Kanten in den bestehenden Collections `${prefix}_notes`, `${prefix}_chunks`, `${prefix}_edges`.
- Status: Implementiert und durch `tests/test_edges_smoke.py`, `tests/test_edges_all.py` und `scripts/edges_full_check.py` verifiziert.
### Step 3 – Chunker v2
- Implementierung & Flag `--chunker v2`.
- **Abnahme:** Chunk‑Counts ~ alt (≈171 ± 15 %), semantische Schnitte.
@@ -208,6 +238,17 @@ rule_sets:
- Reihenfolge & `provenance` strikt umsetzen, `default_resolved` integrieren.
- **Abnahme:** erwartete Relationensätze auf Gold‑Notizen, keine Duplikate.
### Step 4a – Edge-bewusster Retriever
- Implementiere einen Retrieval-Service, der:
- Chunks über Vektor-Suche aus `${prefix}_chunks` holt,
- dazu passende Nachbar-Chunks (`next/prev`) und typrelevante Notizen (`edge_defaults`, Inline-Relationen, Wikilinks) über `${prefix}_edges` ergänzt,
- `retriever_weight` und `confidence` beim Scoring berücksichtigt.
- Liefere einen API-Endpoint `/mindnet/query` mit einem einfachen JSON-Response (Chunks + Begründung).
- Akzeptanz:
- mindestens ein Testfall mit dem Relations-Showcase-Vault,
- sichtbarer Einfluss von `edge_defaults` und Inline-Relationen auf die Ergebnisliste.
### Step 5 – Importer‑Pipeline v2
- `--schema v2` Side‑by‑Side; Batch‑Upserts; vollständige Payloads; Recency‑Boost Konfig **nur** in Policy.
- **Abnahme:** Dry‑Run/Apply‑Parität, Reports, Telemetrie‑Ereignisse sichtbar.
+260
View File
@@ -0,0 +1,260 @@
# WP-04 / Step 4a – Retriever Scoring & Konfiguration
Dieses Dokument beschreibt den aktuellen Stand (2025-11-30) der Scoring-Logik des mindnet-Retrievers in WP-04 / Step 4a.
Es dient als Referenz für:
- Nachvollziehbarkeit des Rankings
- Konfiguration und Feintuning (ohne Codeänderungen)
- spätere Automatisierung / „Selbstjustierung“ des Retrievers
---
## 1. Überblick
Der Retriever kombiniert drei Signalquellen zu einem einheitlichen Score:
1. **Semantik** – Vektorsuche über `mindnet_chunks`
2. **Typ-Gewichtung** – `retriever_weight` pro Note/Chunk (aus `types.yaml`)
3. **Graph-Boni** – `edge_bonus` und `centrality_bonus` aus dem Subgraph (Edges)
Die Berechnung erfolgt in `app/core/retriever.py` und ist über `config/retriever.yaml` konfigurierbar.
Die API stellt die Funktionalität über den `/query`-Endpoint (FastAPI) bereit.
---
## 2. Datenbasis (Kurzüberblick)
### 2.1 Notes (`<prefix>_notes`)
Relevante Felder:
- note_id: keyword
- title: text
- type: keyword
- retriever_weight: float
- chunk_profile: keyword
- edge_defaults: keyword[]
- tags: keyword[]
- path: text
- fulltext: text
### 2.2 Chunks (`<prefix>_chunks`)
Relevante Felder:
- note_id: keyword
- chunk_id: keyword
- text: text
- window: text
- retriever_weight: float
- type: keyword
- path: text
- section: text
- neighbors_prev / neighbors_next
- chunk_profile: keyword
### 2.3 Edges (`<prefix>_edges`)
Relevante Felder:
- kind: keyword
- source_id: keyword
- target_id: keyword
- note_id: keyword
- confidence: float
- rule_id, provenance, edge_id, scope, relation, ref_text
Edges stammen stets aus der Import-/Edge-Pipeline (WP-03) und bilden die graphbasierte Grundlage des Retrievers.
---
## 3. Scoring-Formel (Retriever)
### 3.1 Eingangsgrößen
Für jeden Treffer gelten:
semantic_score – aus der Vektorsuche (Qdrant)
retriever_weight – typabhängiges Gewicht (aus types.yaml)
edge_bonus – aggregierter Graph-Bonus
centrality_bonus – Zentralitätsbonus aus dem Subgraph
### 3.2 Globale Gewichte (aus retriever.yaml)
Datei: `config/retriever.yaml`
Beispiel:
version: 1.0
scoring:
semantic_weight: 1.0 # W_sem
edge_weight: 0.7 # W_edge
centrality_weight: 0.5 # W_cent
Falls diese Datei fehlt, greifen ENV-basierte Defaults (`RETRIEVER_W_*`).
### 3.3 Formel
total_score =
W_sem * semantic_score * max(retriever_weight, 0.0)
+ W_edge * edge_bonus
+ W_cent * centrality_bonus
Bemerkungen:
- Negative `retriever_weight` werden abgefangen.
- Die rohen `edge_bonus` und `centrality_bonus` werden im API-/Smoke-Output angezeigt.
- Die Gewichte aus `retriever.yaml` beeinflussen **nur den total_score**, nicht die Anzeige.
---
## 4. Konfigurationsdateien
### 4.1 Typen-Registry (`types.yaml`)
Beispielauszug:
defaults:
retriever_weight: 1.0
chunk_profile: default
types:
types:
concept:
retriever_weight: 0.60
edge_defaults: ["references", "related_to"]
project:
retriever_weight: 0.97
edge_defaults: ["references", "depends_on"]
journal:
retriever_weight: 0.80
edge_defaults: ["references", "related_to"]
source:
retriever_weight: 0.50
edge_defaults: []
Diese Werte bestimmen, wie wichtig eine Note/Chunk **prinzipiell** für den Retriever ist.
### 4.2 Retriever-Konfiguration (`retriever.yaml`)
Beispiel:
version: 1.0
scoring:
semantic_weight: 1.0
edge_weight: 0.7
centrality_weight: 0.5
# Blueprint für spätere Edge-Feinsteuerung:
edge_types:
references: 0.20
depends_on: 0.18
related_to: 0.15
similar_to: 0.12
belongs_to: 0.10
next: 0.06
prev: 0.06
Die Datei befindet sich standardmäßig unter `config/retriever.yaml`.
Override per ENV:
MINDNET_RETRIEVER_CONFIG=/pfad/zur/datei.yaml
### 4.3 Aktive Gewichte auslesen
python - << 'PY'
from app.core.retriever import _get_scoring_weights
print(_get_scoring_weights())
PY
Beispielausgabe:
(1.0, 0.7, 0.5)
---
## 5. Betriebsmodi
### 5.1 Semantikmodus (semantic)
Ablauf:
- Query-Vektor über embed_text()
- Qdrant-Suche über mindnet_chunks
- kein Subgraph → edge_bonus = centrality = 0
- total_score = W_sem * semantic_score * retriever_weight
### 5.2 Hybridmodus (hybrid)
Ablauf:
- Semantik wie oben
- falls expand.depth > 0:
- Subgraph-Berechnung über ga.expand()
- Ermittlung von edge_bonus und centrality_bonus
- total_score = kombinierte Formel aus Semantik + Graph
---
## 6. Tests
### Ausführung (Unit & Integration)
pytest tests/test_retriever_basic.py \
tests/test_retriever_weight.py \
tests/test_retriever_edges.py
pytest tests/test_query_unit.py \
tests/test_query_text_embed_unit.py
Tests decken ab:
- Semantiktreffer
- Typ-Gewichte
- Edge-Boni
- Hybridmodus / FastAPI-Endpunkt
### Smoke-Test
python tests/test_retriever_smoke.py \
--url "http://127.0.0.1:8001/query" \
--query "embeddings" \
--mode hybrid \
--expand-depth 1 \
--top-k 5
Beispielausgabe:
[1] note_id=...retriever-design
total=1.5054 (semantic=0.4038 edge=1.5910 centrality=0.0000)
Interpretation:
- `semantic`, `edge`, `centrality` = Rohwerte
- `total` = skaliert mit `retriever.yaml`
---
## 7. Betriebs-Hinweise
### 7.1 Änderung der Gewichte
- retriever.yaml anpassen
- FastAPI/uvicorn neu starten
- Smoke-Test prüfen
### 7.2 Zielbild WP-04
Der jetzige Stand ermöglicht:
- transparente, konfigurierbare Score-Berechnung
- Kombination aus Semantik, Typwissen und Graphstruktur
- spätere agentenbasierte Selbstjustierung
- alternative Profile (z. B. „mehr Semantik“, „mehr Graph“)
Dieses Dokument dient als stabile Referenz für Entwickler, Tests und spätere Automatisierungsschritte.
+163
View File
@@ -0,0 +1,163 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/edges_full_check.py
Zählt und validiert Kanten in Qdrant. Erkennt folgende Rule-Gruppen:
- explicit_total: rule_id startswith "explicit:" (z.B. explicit:wikilink, explicit:note_scope)
- callout_total: rule_id == "callout:edge"
- inline_total: rule_id startswith "inline:" (z.B. inline:rel)
- defaults_total: rule_id startswith "edge_defaults:"
- structure: rule_id in {"structure:belongs_to","structure:order"}
Gibt zusätzlich:
- edges_by_kind (aggregiert)
- notes/chunks/edges Anzahlen
- multi_callout_detected: True, falls ein Chunk mehrere Callout-Ziele der gleichen Relation enthält
- per_note_checks: belongs_to == chunks, next == prev == (chunks-1)
"""
from __future__ import annotations
import json
from collections import Counter, defaultdict
from typing import Dict, Any, List, Tuple
from app.core.qdrant import QdrantConfig, get_client
from qdrant_client.http import models as rest
def _count_collection_points(client, name: str) -> int:
try:
res = client.count(collection_name=name, exact=True)
return res.count or 0
except Exception:
return 0
def _scroll_all(client, collection: str) -> List[Any]:
pts_all = []
offset = None
while True:
pts, offset = client.scroll(
collection_name=collection,
with_payload=True,
with_vectors=False,
limit=2048,
offset=offset,
)
pts_all.extend(pts or [])
if offset is None:
break
return pts_all
def _rule_group(rule_id: str) -> str:
if not rule_id:
return "unknown"
if rule_id == "callout:edge":
return "callout"
if rule_id.startswith("inline:"): # <—— wichtig für "inline:rel"
return "inline"
if rule_id.startswith("edge_defaults:"):
return "defaults"
if rule_id.startswith("explicit:"):
return "explicit"
if rule_id in ("structure:belongs_to", "structure:order"):
return "structure"
return "other"
def main() -> None:
cfg = QdrantConfig.from_env()
client = get_client(cfg)
col_notes = f"{cfg.prefix}_notes"
col_chunks = f"{cfg.prefix}_chunks"
col_edges = f"{cfg.prefix}_edges"
# High-level counts
notes_n = _count_collection_points(client, col_notes)
chunks_n = _count_collection_points(client, col_chunks)
edges_pts = _scroll_all(client, col_edges)
edges_n = len(edges_pts)
# By kind / by rule group
by_kind = Counter()
group_counts = Counter()
callout_buckets: Dict[Tuple[str, str], int] = defaultdict(int) # (chunk_id, kind) -> n targets
per_note = defaultdict(lambda: {"chunks": 0, "belongs_to": 0, "next": 0, "prev": 0})
# Für per_note checks: chunks pro note_id aus mindnet_chunks laden
chunks_pts = _scroll_all(client, col_chunks)
chunks_by_note = Counter([p.payload.get("note_id") for p in chunks_pts if p.payload])
for p in edges_pts:
pl = p.payload or {}
kind = str(pl.get("kind") or pl.get("relation") or "edge")
rule_id = str(pl.get("rule_id") or "")
note_id = str(pl.get("note_id") or "")
chunk_id = str(pl.get("chunk_id") or "")
by_kind[kind] += 1
group = _rule_group(rule_id)
group_counts[group] += 1
# Multi-Callout-Erkennung: mehrere callout-Edges gleicher Relation aus demselben Chunk
if group == "callout" and chunk_id and kind:
callout_buckets[(chunk_id, kind)] += 1
# Per-note Strukturchecks
if note_id:
if kind == "belongs_to":
per_note[note_id]["belongs_to"] += 1
elif kind == "next":
per_note[note_id]["next"] += 1
elif kind == "prev":
per_note[note_id]["prev"] += 1
# set chunks count for per_note
for n_id, c in chunks_by_note.items():
per_note[n_id]["chunks"] = c
# final checks per note
per_note_checks = {}
for n_id, stats in per_note.items():
c = stats.get("chunks", 0)
bt = stats.get("belongs_to", 0)
nx = stats.get("next", 0)
pv = stats.get("prev", 0)
per_note_checks[n_id] = {
"chunks": c,
"belongs_to": bt,
"next": nx,
"prev": pv,
"checks": {
"belongs_to_equals_chunks": (bt == c),
"next_prev_match": (nx == pv == max(c - 1, 0)),
},
}
multi_callout_detected = any(v > 1 for v in callout_buckets.values())
out = {
"prefix": cfg.prefix,
"counts": {
"notes": notes_n,
"chunks": chunks_n,
"edges": edges_n,
"edges_by_kind": dict(by_kind),
"explicit_total": group_counts.get("explicit", 0),
"defaults_total": group_counts.get("defaults", 0),
"callout_total": group_counts.get("callout", 0),
"inline_total": group_counts.get("inline", 0),
"structure_total": group_counts.get("structure", 0),
},
"per_note_checks": per_note_checks,
"multi_callout_detected": bool(multi_callout_detected),
"has_duplicates": False, # dedupe passiert beim Upsert
}
print(json.dumps(out, ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
+340
View File
@@ -0,0 +1,340 @@
#!/usr/bin/env python3
"""
scripts/health_check_mindnet.py
Health-Check für den mindnet-Retriever-/Query-Endpoint.
Funktion:
- Führt POST-Requests auf /query in verschiedenen Modi aus (standard: semantic + hybrid).
- Prüft Status-Code, JSON-Struktur und Anzahl der Treffer.
- Kennzeichnet Probleme als:
- status="ok"
- status="warning" (z.B. Timeout)
- status="error" (harte Fehler wie HTTP-Fehler, JSON-Fehler etc.)
Exit-Code:
- Default (tolerant):
- overall_status = "ok" (inkl. warnings) → Exit-Code 0
- overall_status = "error" → Exit-Code 1
- Mit --strict:
- warnings werden wie errors behandelt → Exit-Code 1
Beispiele:
python scripts/health_check_mindnet.py \
--url http://127.0.0.1:8001/query \
--query "embeddings" \
--top-k 3
python scripts/health_check_mindnet.py \
--url http://127.0.0.1:8001/query \
--query "embeddings" \
--top-k 3 \
--timeout 15 \
--modes hybrid
# Strenger Modus (warnings → Exit-Code 1)
python scripts/health_check_mindnet.py --strict
"""
from __future__ import annotations
import argparse
import json
import socket
import sys
import time
import urllib.error
import urllib.request
from typing import Any, Dict, List
def _post_query(
url: str,
mode: str,
query: str,
top_k: int,
timeout: float,
) -> Dict[str, Any]:
"""
Führt einen POST auf den /query-Endpoint aus und gibt das dekodierte JSON zurück.
Raises:
urllib.error.URLError, urllib.error.HTTPError, RuntimeError
"""
payload = {
"mode": mode,
"query": query,
"top_k": top_k,
"expand": {
"depth": 1 if mode == "hybrid" else 0,
"edge_types": ["references", "belongs_to", "prev", "next"],
},
"ret": {
"with_paths": True,
"with_notes": True,
"with_chunks": True,
},
}
data = json.dumps(payload).encode("utf-8")
req = urllib.request.Request(
url=url,
data=data,
headers={"Content-Type": "application/json"},
method="POST",
)
start = time.monotonic()
with urllib.request.urlopen(req, timeout=timeout) as resp:
status_code = resp.getcode()
body = resp.read().decode("utf-8")
end = time.monotonic()
latency_ms = int((end - start) * 1000)
if status_code != 200:
raise RuntimeError(f"HTTP {status_code}: {body}")
try:
doc = json.loads(body)
except json.JSONDecodeError as exc:
raise RuntimeError(f"Antwort ist kein gültiges JSON: {exc}") from exc
if not isinstance(doc, dict):
raise RuntimeError("Antwort ist kein JSON-Objekt")
doc["_latency_ms"] = latency_ms
return doc
def _validate_response(
mode: str,
doc: Dict[str, Any],
min_results: int,
) -> Dict[str, Any]:
"""
Prüft die wichtigsten Invarianten des Query-Responses.
Rückgabe-Format:
{
"status": "ok" | "warning" | "error",
"message": str,
"latency_ms": int,
"used_mode": str,
"result_count": int
}
"""
latency_ms = int(doc.get("_latency_ms", -1))
used_mode = str(doc.get("used_mode", "unknown"))
results = doc.get("results", [])
if not isinstance(results, list):
return {
"status": "error",
"message": "results ist kein Array",
"latency_ms": latency_ms,
"used_mode": used_mode,
"result_count": -1,
}
result_count = len(results)
if result_count < min_results:
# Zu wenige Ergebnisse sind aus Sicht eines Health-Checks eher ein Error,
# da die Retrieval-Qualität nicht gewährleistet ist.
return {
"status": "error",
"message": f"zu wenige Ergebnisse: {result_count} < {min_results}",
"latency_ms": latency_ms,
"used_mode": used_mode,
"result_count": result_count,
}
sample_msg = "OK"
if result_count > 0:
first = results[0]
if not isinstance(first, dict):
sample_msg = "first result ist kein Objekt"
else:
# einfache Plausibilitätschecks (nur Zugriff, kein strikter Typcheck)
_ = first.get("note_id")
_ = first.get("chunk_id")
_ = first.get("total_score")
status = "ok" if sample_msg == "OK" else "warning"
return {
"status": status,
"message": sample_msg,
"latency_ms": latency_ms,
"used_mode": used_mode,
"result_count": result_count,
}
def run_health_check(
url: str,
query: str,
top_k: int,
timeout: float,
modes: List[str],
min_results: int,
) -> Dict[str, Any]:
"""
Führt den Health-Check für die angegebenen Modi aus.
"""
report: Dict[str, Any] = {
"url": url,
"query": query,
"top_k": top_k,
"timeout_s": timeout,
"checks": [],
"overall_status": "ok", # wird unten ggf. auf warning oder error gesetzt
}
overall_status = "ok"
for mode in modes:
entry: Dict[str, Any] = {
"mode": mode,
"status": "error",
"message": "",
}
try:
doc = _post_query(url=url, mode=mode, query=query, top_k=top_k, timeout=timeout)
validation = _validate_response(mode=mode, doc=doc, min_results=min_results)
entry.update(validation)
except urllib.error.HTTPError as exc:
entry["status"] = "error"
entry["message"] = f"HTTP-Fehler: {exc}"
entry["latency_ms"] = -1
entry["used_mode"] = mode
entry["result_count"] = -1
except urllib.error.URLError as exc:
# URLError kann u.a. socket.timeout enthalten.
lat = -1
entry["latency_ms"] = lat
entry["used_mode"] = mode
entry["result_count"] = -1
if isinstance(exc.reason, socket.timeout):
entry["status"] = "warning"
entry["message"] = f"Timeout (URLError/socket.timeout): {exc}"
else:
entry["status"] = "error"
entry["message"] = f"HTTP/Netzwerkfehler: {exc}"
except socket.timeout as exc:
# Direkter Timeout (falls nicht in URLError verpackt)
entry["status"] = "warning"
entry["message"] = f"Timeout (socket.timeout): {exc}"
entry["latency_ms"] = -1
entry["used_mode"] = mode
entry["result_count"] = -1
except Exception as exc: # noqa: BLE001
entry["status"] = "error"
entry["message"] = f"unerwarteter Fehler: {exc}"
entry["latency_ms"] = -1
entry["used_mode"] = mode
entry["result_count"] = -1
# overall_status bestimmen:
# - error > warning > ok
if entry["status"] == "error":
overall_status = "error"
elif entry["status"] == "warning" and overall_status == "ok":
overall_status = "warning"
report["checks"].append(entry)
report["overall_status"] = overall_status
return report
def parse_args(argv: List[str]) -> argparse.Namespace:
parser = argparse.ArgumentParser(
description="Health-Check für mindnet /query-Retriever",
)
parser.add_argument(
"--url",
default="http://127.0.0.1:8001/query",
help="Vollständige URL des /query-Endpunkts (Default: %(default)s)",
)
parser.add_argument(
"--query",
default="embeddings",
help="Test-Query für den Health-Check (Default: %(default)s)",
)
parser.add_argument(
"--top-k",
type=int,
default=3,
help="Top-K für die Testabfrage (Default: %(default)s)",
)
parser.add_argument(
"--timeout",
type=float,
default=5.0,
help="Timeout in Sekunden pro Request (Default: %(default)s)",
)
parser.add_argument(
"--modes",
nargs="+",
default=["semantic", "hybrid"],
help="Zu prüfende Modi (Default: semantic hybrid)",
)
parser.add_argument(
"--min-results",
type=int,
default=1,
help="Minimale Anzahl erwarteter Ergebnisse (Default: %(default)s)",
)
parser.add_argument(
"--strict",
action="store_true",
help="Warnings als Fehler behandeln (overall_status=warning führt zu Exit-Code 1)",
)
return parser.parse_args(argv)
def main(argv: List[str]) -> int:
args = parse_args(argv)
report = run_health_check(
url=args.url,
query=args.query,
top_k=args.top_k,
timeout=args.timeout,
modes=args.modes,
min_results=args.min_results,
)
overall = report.get("overall_status", "error")
# Menschlich lesbare Zusammenfassung:
print(f"mindnet health: {overall}")
for c in report["checks"]:
mode = c.get("mode")
status = c.get("status")
latency = c.get("latency_ms")
result_count = c.get("result_count")
msg = c.get("message", "")
print(f" - {mode}: {status} (latency={latency} ms, results={result_count}) {msg}")
# JSON-Ausgabe (z.B. für n8n):
print(json.dumps(report, ensure_ascii=False))
if args.strict:
# strict: warning wird wie error behandelt
return 0 if overall == "ok" else 1
else:
# tolerant: nur echte errors führen zu Exit-Code 1
return 0 if overall in ("ok", "warning") else 1
if __name__ == "__main__":
raise SystemExit(main(sys.argv[1:]))
+104
View File
@@ -0,0 +1,104 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Kleine Diagnosehilfe für mindnet_edges.
Nutzung (aus Projektwurzel):
(.venv) python tests/diag_edges_for_note.py \
--note-id 20251130-relshow-embeddings-101
Optional:
--prefix mindnet
Ziel:
- Zeigt alle Edges aus der Collection <prefix>_edges,
die sich auf die angegebene note_id beziehen:
* note_id == NOTE
* oder source_id == NOTE
* oder target_id == NOTE
"""
from __future__ import annotations
import argparse
import os
import sys
from typing import List
# Projekt-Root (Ordner mit "app/") zum sys.path hinzufügen,
# damit "import app.core.qdrant" funktioniert, auch wenn das Script
# direkt aus tests/ gestartet wird.
THIS_DIR = os.path.dirname(os.path.abspath(__file__))
PROJECT_ROOT = os.path.dirname(THIS_DIR)
if PROJECT_ROOT not in sys.path:
sys.path.insert(0, PROJECT_ROOT)
from qdrant_client.http import models as rest # type: ignore
from app.core.qdrant import QdrantConfig, get_client, collection_names
def fetch_edges_for_note(note_id: str, prefix: str | None, limit: int = 512) -> List[dict]:
cfg = QdrantConfig.from_env()
if prefix:
cfg.prefix = prefix
client = get_client(cfg)
_, _, edges_col = collection_names(cfg.prefix)
conditions = []
for field in ("note_id", "source_id", "target_id"):
conditions.append(
rest.FieldCondition(
key=field,
match=rest.MatchValue(value=str(note_id)),
)
)
flt = rest.Filter(
should=conditions,
)
points, _ = client.scroll(
collection_name=edges_col,
scroll_filter=flt,
with_payload=True,
with_vectors=False,
limit=limit,
)
out: List[dict] = []
for p in points or []:
pl = dict(p.payload or {})
if pl:
out.append(pl)
return out
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument("--note-id", required=True, help="Note-ID, z. B. 20251130-relshow-embeddings-101")
parser.add_argument("--prefix", default=None, help="Qdrant-Prefix (Default: aus ENV/QdrantConfig)")
args = parser.parse_args()
note_id = args.note_id
prefix = args.prefix
edges = fetch_edges_for_note(note_id, prefix)
print(f"Prefix: {prefix or '(aus ENV)'}")
print(f"Note-ID: {note_id}")
print(f"Gefundene Edges: {len(edges)}")
print("-" * 60)
for i, e in enumerate(edges, start=1):
print(f"[{i}] kind={e.get('kind')} confidence={e.get('confidence')}")
print(f" note_id = {e.get('note_id')}")
print(f" source_id= {e.get('source_id')}")
print(f" target_id= {e.get('target_id')}")
print()
if __name__ == "__main__":
main()
+120
View File
@@ -0,0 +1,120 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Diagnose für den Graph-Adapter (Subgraph) in mindnet.
Nutzung (aus Projektwurzel):
(.venv) python tests/diag_subgraph_for_note.py \
--note-id 20251130-relshow-embeddings-101 \
--depth 1
Optional:
--prefix mindnet
--edge-type references --edge-type related_to ...
Ziel:
- Ruft app.core.graph_adapter.expand(...) für eine gegebene note_id auf.
- Gibt edge_bonus und centrality_bonus für diese note_id aus.
- Zeigt zusätzlich einige Nachbarn und deren Boni.
"""
from __future__ import annotations
import argparse
import os
import sys
from typing import List, Optional, Tuple
# sys.path anpassen, damit "import app...." aus tests/ funktioniert
THIS_DIR = os.path.dirname(os.path.abspath(__file__))
PROJECT_ROOT = os.path.dirname(THIS_DIR)
if PROJECT_ROOT not in sys.path:
sys.path.insert(0, PROJECT_ROOT)
from app.core.qdrant import QdrantConfig, get_client # type: ignore
import app.core.graph_adapter as ga # type: ignore
def build_subgraph_for_note(
note_id: str,
prefix: Optional[str],
depth: int,
edge_types: Optional[List[str]] = None,
) -> Tuple[ga.Subgraph, str]:
cfg = QdrantConfig.from_env()
if prefix:
cfg.prefix = prefix
client = get_client(cfg)
sg = ga.expand(client, cfg.prefix, [note_id], depth=depth, edge_types=edge_types)
return sg, cfg.prefix
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument(
"--note-id",
required=True,
help="Note-ID, z. B. 20251130-relshow-embeddings-101",
)
parser.add_argument(
"--depth",
type=int,
default=1,
help="Expansionstiefe (Default: 1)",
)
parser.add_argument(
"--prefix",
default=None,
help="Qdrant-Prefix (Default: aus ENV/QdrantConfig)",
)
parser.add_argument(
"--edge-type",
action="append",
default=None,
help="Edge-Typ-Filter (kann mehrfach angegeben werden), z. B. --edge-type references",
)
args = parser.parse_args()
note_id = args.note_id
depth = max(0, int(args.depth))
prefix = args.prefix
edge_types = args.edge_type
sg, eff_prefix = build_subgraph_for_note(note_id, prefix, depth, edge_types=edge_types)
print(f"Prefix: {eff_prefix}")
print(f"Note-ID (Seed): {note_id}")
print(f"Depth: {depth}")
print(f"Edge-Types-Filter: {edge_types or '(keiner)'}")
print("-" * 60)
# Boni für die Seed-Note
eb = sg.edge_bonus(note_id)
cb = sg.centrality_bonus(note_id)
print(f"edge_bonus({note_id}) = {eb:.4f}")
print(f"centrality_bonus({note_id}) = {cb:.4f}")
print("-" * 60)
# Ein paar weitere Knoten anzeigen (falls vorhanden)
print("Beispiele weiterer Knoten mit Boni (max. 10):")
printed = 0
for node, edges in sg.adj.items():
if node == note_id:
continue
if printed >= 10:
break
eb2 = sg.edge_bonus(node)
cb2 = sg.centrality_bonus(node)
print(f"- node={node}")
print(f" edge_bonus={eb2:.4f} centrality={cb2:.4f}")
printed += 1
if printed == 0:
print("(keine weiteren Knoten im Subgraph registriert)")
if __name__ == "__main__":
main()
+122
View File
@@ -0,0 +1,122 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/test_retriever_smoke.py - einfacher Smoke-Test für den mindnet-Retriever
Zweck:
- Startet eine Query gegen die laufende FastAPI-Instanz
- Prüft, ob der /query-Endpunkt antwortet und sinnvolle Treffer liefert
- Gibt Top-K-Ergebnisse inkl. Scores auf stdout aus
Verwendung:
1) Stelle sicher, dass der mindnet-Service läuft, z. B.:
uvicorn app.main:create_app --factory --reload
2) Führe dieses Skript aus:
python scripts/test_retriever_smoke.py --query "karate" --mode hybrid
3) Optional:
python scripts/test_retriever_smoke.py --query "embeddings" --mode semantic --top-k 5
Hinweis:
- Standard-URL ist http://127.0.0.1:8000
- Endpoint ist /query (bestehender Router), der QueryRequest erwartet
"""
from __future__ import annotations
import argparse
import json
import sys
from typing import Any, Dict
import requests
def _build_payload(args: argparse.Namespace) -> Dict[str, Any]:
payload: Dict[str, Any] = {
"mode": args.mode,
"query": args.query,
"top_k": args.top_k,
}
if args.expand_depth is not None and args.expand_depth > 0:
expand: Dict[str, Any] = {"depth": args.expand_depth}
if args.expand_edge_types:
expand["edge_types"] = args.expand_edge_types
payload["expand"] = expand
return payload
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description="Smoke-Test für mindnet-Retriever (/query)")
parser.add_argument("--url", default="http://127.0.0.1:8000/query", help="Basis-URL des Query-Endpunkts")
parser.add_argument("--query", required=True, help="Text-Query für den Retriever")
parser.add_argument("--mode", choices=["semantic", "hybrid"], default="hybrid", help="Retrieval-Modus")
parser.add_argument("--top-k", type=int, default=5, help="Anzahl der gewünschten Treffer")
parser.add_argument("--expand-depth", type=int, default=0, help="Edge-Expansionstiefe (nur hybrid)")
parser.add_argument(
"--expand-edge-types",
nargs="*",
default=None,
help="Liste von Edge-Typen für die Expansion (z. B. references depends_on)",
)
args = parser.parse_args(argv)
payload = _build_payload(args)
try:
resp = requests.post(args.url, json=payload, timeout=10)
except Exception as exc: # pragma: no cover - Netzwerkfehler
print(f"[ERROR] HTTP-Request fehlgeschlagen: {exc}", file=sys.stderr)
return 1
if resp.status_code != 200:
print(f"[ERROR] Unerwarteter Statuscode: {resp.status_code}", file=sys.stderr)
print(resp.text, file=sys.stderr)
return 1
try:
data = resp.json()
except Exception as exc: # pragma: no cover - JSON-Fehler
print(f"[ERROR] Antwort ist kein gültiges JSON: {exc}", file=sys.stderr)
print(resp.text, file=sys.stderr)
return 1
print("=== mindnet Retriever Smoke-Test ===")
print(f"URL: {args.url}")
print(f"Mode: {args.mode}")
print(f"Query: {args.query!r}")
print(f"Top-K: {args.top_k}")
print()
results = data.get("results") or []
used_mode = data.get("used_mode")
latency_ms = data.get("latency_ms")
print(f"used_mode = {used_mode}, latency = {latency_ms} ms")
print(f"Treffer insgesamt: {len(results)}")
print()
for i, hit in enumerate(results, start=1):
note_id = hit.get("note_id")
node_id = hit.get("node_id")
total = hit.get("total_score")
sem = hit.get("semantic_score")
edge_bonus = hit.get("edge_bonus")
cent_bonus = hit.get("centrality_bonus")
src = hit.get("source") or {}
path = src.get("path")
section = src.get("section")
print(f"[{i}] note_id={note_id} node_id={node_id}")
print(f" total={total:.4f} (semantic={sem:.4f} edge={edge_bonus:.4f} centrality={cent_bonus:.4f})")
if path or section:
print(f" source: {path or '-'} :: {section or '-'}")
print()
return 0
if __name__ == "__main__": # pragma: no cover
raise SystemExit(main())
+116
View File
@@ -0,0 +1,116 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
tests/test_edges_all.py
Ein knapper Integrationscheck:
- Es existieren Notes/Chunks/Edges
- Inline-Edges (rule_id startswith "inline:") werden erkannt
- Callout-Edges (rule_id == "callout:edge") werden erkannt
- Defaults (rule_id startswith "edge_defaults:") werden erkannt
- Strukturkanten stimmen (belongs_to == chunks; next == prev == chunks-1)
"""
from __future__ import annotations
import json
from collections import Counter, defaultdict
from typing import Dict, Any, List, Tuple
from app.core.qdrant import QdrantConfig, get_client
def _scroll_all(client, collection: str):
pts_all = []
offset = None
while True:
pts, offset = client.scroll(
collection_name=collection,
with_payload=True,
with_vectors=False,
limit=2048,
offset=offset,
)
pts_all.extend(pts or [])
if offset is None:
break
return pts_all
def _rule_group(rule_id: str) -> str:
if not rule_id:
return "unknown"
if rule_id == "callout:edge":
return "callout"
if rule_id.startswith("inline:"): # <—— wichtig für inline:rel
return "inline"
if rule_id.startswith("edge_defaults:"):
return "defaults"
if rule_id.startswith("explicit:"):
return "explicit"
if rule_id in ("structure:belongs_to", "structure:order"):
return "structure"
return "other"
def main() -> None:
cfg = QdrantConfig.from_env()
client = get_client(cfg)
col_notes = f"{cfg.prefix}_notes"
col_chunks = f"{cfg.prefix}_chunks"
col_edges = f"{cfg.prefix}_edges"
notes_n = client.count(collection_name=col_notes, exact=True).count
chunks_pts = _scroll_all(client, col_chunks)
edges_pts = _scroll_all(client, col_edges)
ok = True
# Basisbedingungen
if notes_n == 0 or len(chunks_pts) == 0 or len(edges_pts) == 0:
ok = False
# Gruppen zählen
g = Counter(_rule_group((p.payload or {}).get("rule_id", "")) for p in edges_pts)
structure = g.get("structure", 0)
explicit = g.get("explicit", 0)
inline = g.get("inline", 0)
callout = g.get("callout", 0)
defaults = g.get("defaults", 0)
if structure == 0:
ok = False
# mindestens eine der expliziten Varianten vorhanden
if (explicit + inline + callout) == 0:
ok = False
# defaults dürfen 0 sein, wenn types.yaml keine edge_defaults liefert – daher nur Info
# per-note checks
chunks_by_note = Counter([p.payload.get("note_id") for p in chunks_pts if p.payload])
belongs = Counter(
(p.payload or {}).get("note_id")
for p in edges_pts
if (p.payload or {}).get("kind") == "belongs_to"
)
nxt = Counter(
(p.payload or {}).get("note_id")
for p in edges_pts
if (p.payload or {}).get("kind") == "next"
)
prv = Counter(
(p.payload or {}).get("note_id")
for p in edges_pts
if (p.payload or {}).get("kind") == "prev"
)
for n_id, c in chunks_by_note.items():
if belongs.get(n_id, 0) != c:
ok = False
if (nxt.get(n_id, 0) != max(c - 1, 0)) or (prv.get(n_id, 0) != max(c - 1, 0)):
ok = False
print(json.dumps({"ok": ok, "notes_checked": len(chunks_by_note)}, ensure_ascii=False))
if __name__ == "__main__":
main()
+25
View File
@@ -0,0 +1,25 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
tests/test_edges_defaults_smoke.py
Aggregiert Edges je Relation (kind) in Qdrant zur schnellen Sichtprüfung.
Zeigt, ob typenbasierte edge_defaults-Relationen (z. B. depends_on/related_to) auftauchen.
"""
from __future__ import annotations
from collections import Counter
import json
from app.core.qdrant import QdrantConfig, get_client
def main():
cfg = QdrantConfig.from_env()
cl = get_client(cfg)
col = f"{cfg.prefix}_edges"
pts, _ = cl.scroll(collection_name=col, with_payload=True, with_vectors=False, limit=10000)
by_rel = Counter()
for p in pts:
rel = p.payload.get("kind") or p.payload.get("relation") or "edge"
by_rel[rel] += 1
print(json.dumps({"prefix": cfg.prefix, "relations": dict(by_rel)}, ensure_ascii=False))
if __name__ == "__main__":
main()
+107 -114
View File
@@ -1,140 +1,133 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/test_edges_smoke.py — Progressive Ausgabe
Prüft edge-Integrität je Note mit Live-Ausgabe:
- belongs_to == #Chunks
- next == prev == max(#Chunks-1,0)
- Duplikat-Edges (Key: (kind,source_id,target_id,scope)) == 0
- Zählt references (chunk/note), backlink
Optionen:
--max-notes N : prüft nur die ersten N Notizen
--limit L : Scroll-Limit pro Anfrage (Default 256)
--flush : jede Zeile sofort flushen
"""
from __future__ import annotations
import os, sys, json, argparse
from typing import Dict, Any, List, Tuple, Set
import json
import os
from collections import Counter, defaultdict
from qdrant_client.http import models as rest
from app.core.qdrant import QdrantConfig, get_client
def collections(prefix: str) -> Tuple[str, str, str]:
return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges"
def scroll_iter(client, collection: str, filt: rest.Filter | None, with_payload: bool, limit: int):
def _rel(pl: dict) -> str:
return pl.get("relation") or pl.get("kind") or "edge"
def _scroll(client, col):
pts = []
next_page = None
while True:
pts, next_page = client.scroll(
collection_name=collection,
scroll_filter=filt,
with_payload=with_payload,
res, next_page = client.scroll(
collection_name=col,
with_payload=True,
with_vectors=False,
limit=limit,
limit=1024,
offset=next_page,
)
if not pts:
break
for p in pts:
yield p
pts.extend(res)
if next_page is None:
break
return pts
def list_notes(client, prefix: str, limit: int, max_notes: int | None) -> List[Dict[str, Any]]:
notes_col, _, _ = collections(prefix)
out: List[Dict[str, Any]] = []
for p in scroll_iter(client, notes_col, None, True, limit):
pl = p.payload or {}
nid = pl.get("note_id") or pl.get("id")
if nid:
out.append({"note_id": nid, "title": pl.get("title"), "type": pl.get("type")})
if max_notes is not None and len(out) >= max_notes:
break
return out
def count_chunks_for_note(client, prefix: str, note_id: str, limit: int) -> int:
_, chunks_col, _ = collections(prefix)
f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
return sum(1 for _ in scroll_iter(client, chunks_col, f, False, limit))
def fetch_edges_for_note(client, prefix: str, note_id: str, limit: int) -> List[Dict[str, Any]]:
_, _, edges_col = collections(prefix)
f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
return [p.payload or {} for p in scroll_iter(client, edges_col, f, True, limit)]
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--max-notes", type=int)
ap.add_argument("--limit", type=int, default=256)
ap.add_argument("--flush", action="store_true")
args = ap.parse_args()
cfg = QdrantConfig.from_env()
client = get_client(cfg)
prefix = os.environ.get("COLLECTION_PREFIX", cfg.prefix)
notes = list_notes(client, cfg.prefix, args.limit, args.max_notes)
total = {"notes": 0, "chunks": 0, "belongs_to": 0, "next": 0, "prev": 0, "refs_chunk": 0, "refs_note": 0, "backlink": 0, "dup_edges": 0}
cols = {
"notes": f"{prefix}_notes",
"chunks": f"{prefix}_chunks",
"edges": f"{prefix}_edges",
}
for n in notes:
nid = n["note_id"]
total["notes"] += 1
chunk_count = count_chunks_for_note(client, cfg.prefix, nid, args.limit)
total["chunks"] += chunk_count
edges = fetch_edges_for_note(client, cfg.prefix, nid, args.limit)
by_kind = {}
keys: Set[tuple] = set()
dup_count = 0
refs_chunk = 0
refs_note = 0
backlink = 0
for e in edges:
k = e.get("kind")
by_kind[k] = by_kind.get(k, 0) + 1
t = (e.get("kind"), e.get("source_id"), e.get("target_id"), e.get("scope"))
if t in keys:
dup_count += 1
else:
keys.add(t)
if k == "references" and e.get("scope") == "chunk":
refs_chunk += 1
if k == "references" and e.get("scope") == "note":
refs_note += 1
if k == "backlink":
backlink += 1
total["belongs_to"] += by_kind.get("belongs_to", 0)
total["next"] += by_kind.get("next", 0)
total["prev"] += by_kind.get("prev", 0)
total["refs_chunk"] += refs_chunk
total["refs_note"] += refs_note
total["backlink"] += backlink
total["dup_edges"] += dup_count
ok_bt = (by_kind.get("belongs_to", 0) == chunk_count)
ok_seq = (by_kind.get("next", 0) == max(chunk_count - 1, 0) and by_kind.get("prev", 0) == max(chunk_count - 1, 0))
ok_dup = (dup_count == 0)
line = {
"note_id": nid,
"title": n.get("title"),
"type": n.get("type"),
"chunks": chunk_count,
"edges_by_kind": by_kind,
"checks": {
"belongs_to_equals_chunks": ok_bt,
"next_prev_match": ok_seq,
"no_duplicate_edges": ok_dup,
# Index: notes -> title/type
notes_meta = {}
for p in _scroll(client, cols["notes"]):
pl = p.payload or {}
nid = pl.get("note_id")
if nid:
notes_meta[nid] = {
"title": pl.get("title", ""),
"type": pl.get("type", ""),
}
}
print(json.dumps(line, ensure_ascii=False))
if args.flush:
sys.stdout.flush()
print(json.dumps({"prefix": cfg.prefix, "summary": total}, ensure_ascii=False))
# chunks je note
chunks_by_note = defaultdict(int)
for p in _scroll(client, cols["chunks"]):
pl = p.payload or {}
nid = pl.get("note_id")
if nid:
chunks_by_note[nid] += 1
# edges je note
edges_by_note = defaultdict(list)
edges_all = _scroll(client, cols["edges"])
for p in edges_all:
pl = p.payload or {}
nid = pl.get("note_id")
if nid:
edges_by_note[nid].append(pl)
# pro note ausgeben
summary_edges = Counter()
total_chunks = 0
for nid in sorted(notes_meta.keys()):
meta = notes_meta[nid]
chunks = chunks_by_note.get(nid, 0)
total_chunks += chunks
kinds = Counter(_rel(pl) for pl in edges_by_note[nid])
summary_edges.update(kinds)
row = {
"note_id": nid,
"title": meta["title"],
"type": meta["type"],
"chunks": chunks,
"edges_by_kind": dict(kinds),
"checks": {
"belongs_to_equals_chunks": (kinds.get("belongs_to", 0) == chunks),
"next_prev_match": (kinds.get("next", 0) == kinds.get("prev", 0) == max(0, chunks - 1)),
"no_duplicate_edges": _no_dupes(edges_by_note[nid]),
},
}
print(json.dumps(row, ensure_ascii=False))
# Gesamtsummary
total_notes = len(notes_meta)
out = {
"prefix": prefix,
"summary": {
"notes": total_notes,
"chunks": total_chunks,
"belongs_to": summary_edges.get("belongs_to", 0),
"next": summary_edges.get("next", 0),
"prev": summary_edges.get("prev", 0),
"refs_chunk": summary_edges.get("references", 0),
"refs_note": summary_edges.get("references_note", 0),
"backlink": summary_edges.get("backlink", 0),
"dup_edges": 0, # per-Note geprüft
},
}
print(json.dumps(out, ensure_ascii=False))
def _no_dupes(pls):
seen = set()
for pl in pls:
key = (
str(pl.get("source_id") or ""),
str(pl.get("target_id") or ""),
str(pl.get("relation") or pl.get("kind") or ""),
str(pl.get("rule_id") or ""),
)
if key in seen:
return False
seen.add(key)
return True
if __name__ == "__main__":
main()
+64
View File
@@ -0,0 +1,64 @@
from app.core import retriever as r
from app.models.dto import QueryRequest
import app.core.qdrant as qdr
import app.core.qdrant_points as qp
import app.services.embeddings_client as ec
class _DummyClient:
"""Minimaler Platzhalter für QdrantClient in Unit-Tests."""
pass
def _fake_get_client(cfg):
return _DummyClient()
def _fake_embed_text(text: str):
# Liefert stabilen Vektor; Größe ist für diesen Test egal,
# da search_chunks_by_vector ebenfalls gefaked wird.
return [0.0] * 16
def _fake_search_chunks_by_vector(client, prefix, vector, top=10, filters=None):
# einfache Hitliste in absteigender Score-Reihenfolge
return [
("chunk:1", 0.9, {"note_id": "note:1", "path": "a.md", "section_title": "S1"}),
("chunk:2", 0.7, {"note_id": "note:2", "path": "b.md", "section_title": "S2"}),
("chunk:3", 0.4, {"note_id": "note:3", "path": "c.md", "section_title": "S3"}),
]
def test_semantic_retrieve_basic(monkeypatch):
# Qdrant- und Embedding-Aufrufe faken
monkeypatch.setattr(qdr, "get_client", _fake_get_client)
monkeypatch.setattr(ec, "embed_text", _fake_embed_text)
monkeypatch.setattr(qp, "search_chunks_by_vector", _fake_search_chunks_by_vector)
req = QueryRequest(mode="semantic", query="karate trainingsplan", top_k=2)
resp = r.semantic_retrieve(req)
assert resp.used_mode == "semantic"
assert len(resp.results) == 2
# Scores absteigend sortiert
scores = [h.total_score for h in resp.results]
assert scores[0] >= scores[1]
# Korrekte Zuordnung von note_id und Quelle
assert resp.results[0].note_id == "note:1"
assert resp.results[0].source["path"] == "a.md"
def test_hybrid_retrieve_basic(monkeypatch):
# Qdrant- und Embedding-Aufrufe faken
monkeypatch.setattr(qdr, "get_client", _fake_get_client)
monkeypatch.setattr(qp, "search_chunks_by_vector", _fake_search_chunks_by_vector)
# Im Hybrid-Modus arbeiten wir im Step-1-Stand nur mit query_vector
req = QueryRequest(mode="hybrid", query_vector=[0.0] * 16, top_k=2)
resp = r.hybrid_retrieve(req)
assert resp.used_mode == "hybrid"
assert len(resp.results) == 2
scores = [h.total_score for h in resp.results]
assert scores[0] >= scores[1]
+74
View File
@@ -0,0 +1,74 @@
from app.core import retriever as r
from app.models.dto import QueryRequest
import app.core.qdrant as qdr
import app.core.qdrant_points as qp
import app.core.graph_adapter as ga
import app.services.embeddings_client as ec
class _DummyClient:
pass
def _fake_get_client(cfg):
return _DummyClient()
def _fake_embed_text(text: str):
# Dimension ist egal, da wir search_chunks_by_vector faken
return [0.0] * 384
def _fake_search_chunks_by_vector(client, prefix, vector, top=10, filters=None):
# Drei Treffer mit identischem semantic_score und retriever_weight,
# aber unterschiedlichen Graph-Boni
return [
("chunk:1", 0.8, {"note_id": "note:1", "chunk_id": "c1", "path": "a.md", "section_title": "S1"}),
("chunk:2", 0.8, {"note_id": "note:2", "chunk_id": "c2", "path": "b.md", "section_title": "S2"}),
("chunk:3", 0.8, {"note_id": "note:3", "chunk_id": "c3", "path": "c.md", "section_title": "S3"}),
]
class _DummySubgraph:
def __init__(self, edge_scores, cent_scores):
self._edge = edge_scores
self._cent = cent_scores
def edge_bonus(self, node_id: str) -> float:
return self._edge.get(node_id, 0.0)
def centrality_bonus(self, node_id: str) -> float:
return self._cent.get(node_id, 0.0)
def _fake_expand(client, prefix, seeds, depth=1, edge_types=None):
# Wir gewichten c2 > c1 > c3
edge_scores = {"c1": 0.1, "c2": 0.5, "c3": 0.0}
cent_scores = {"c1": 0.05, "c2": 0.2, "c3": 0.0}
return _DummySubgraph(edge_scores, cent_scores)
def test_hybrid_retrieve_uses_edge_scores(monkeypatch):
# Qdrant-Client, Embeddings, Chunk-Suche und Graph-Expansion faken
monkeypatch.setattr(qdr, "get_client", _fake_get_client)
monkeypatch.setattr(ec, "embed_text", _fake_embed_text)
monkeypatch.setattr(qp, "search_chunks_by_vector", _fake_search_chunks_by_vector)
monkeypatch.setattr(ga, "expand", _fake_expand)
# expand.depth > 0 triggern, edge_types sind hier egal
req = QueryRequest(mode="hybrid", query="karate", top_k=3, expand={"depth": 1, "edge_types": ["references"]})
resp = r.hybrid_retrieve(req)
assert len(resp.results) == 3
# Da alle semantic_scores und retriever_weight gleich sind,
# bestimmt die Summe aus edge_bonus + centrality_bonus das Ranking.
first = resp.results[0]
second = resp.results[1]
third = resp.results[2]
assert first.note_id == "note:2" # c2 hat höchste Graph-Boni
assert second.note_id == "note:1"
assert third.note_id == "note:3"
assert first.total_score > second.total_score > third.total_score
+120
View File
@@ -0,0 +1,120 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# test_retriever_smoke.py – End-to-End Smoke-Test für den mindnet Retriever
#
# Dieser Smoke-Test ist für manuelle End-to-End-Tests gedacht.
# Er wird NICHT automatisch von pytest ausgeführt.
#
# Empfohlener Speicherort: tests/test_retriever_smoke.py
#
# Aufrufbeispiele:
#
# python tests/test_retriever_smoke.py --query "embeddings" --mode semantic
#
# python tests/test_retriever_smoke.py \
# --query "embeddings" \
# --mode hybrid \
# --expand-depth 1 \
# --expand-edge-types references depends_on
#
from __future__ import annotations
import argparse
import sys
from typing import Any, Dict
import requests
def _build_payload(args: argparse.Namespace) -> Dict[str, Any]:
payload: Dict[str, Any] = {
"mode": args.mode,
"query": args.query,
"top_k": args.top_k,
}
if args.expand_depth is not None and args.expand_depth > 0:
expand: Dict[str, Any] = {"depth": args.expand_depth}
if args.expand_edge_types:
expand["edge_types"] = args.expand_edge_types
payload["expand"] = expand
return payload
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description="Smoke-Test für mindnet-Retriever (/query)")
parser.add_argument("--url", default="http://127.0.0.1:8000/query", help="URL des Query-Endpunkts")
parser.add_argument("--query", required=True, help="Text-Query")
parser.add_argument("--mode", choices=["semantic", "hybrid"], default="hybrid")
parser.add_argument("--top-k", type=int, default=5)
parser.add_argument("--expand-depth", type=int, default=0)
parser.add_argument(
"--expand-edge-types",
nargs="*",
default=None,
help="Edge-Typen (z. B. references depends_on)",
)
args = parser.parse_args(argv)
payload = _build_payload(args)
try:
resp = requests.post(args.url, json=payload, timeout=10)
except Exception as exc:
print(f"[ERROR] HTTP-Request fehlgeschlagen: {exc}", file=sys.stderr)
return 1
if resp.status_code != 200:
print(f"[ERROR] Statuscode: {resp.status_code}", file=sys.stderr)
print(resp.text, file=sys.stderr)
return 1
try:
data = resp.json()
except Exception:
print("[ERROR] Ungültiges JSON:", resp.text, file=sys.stderr)
return 1
print("=== mindnet Retriever Smoke-Test ===")
print(f"URL: {args.url}")
print(f"Mode: {args.mode}")
print(f"Query: {args.query!r}")
print(f"Top-K: {args.top_k}")
print()
results = data.get("results") or []
print(f"used_mode: {data.get('used_mode')}")
print(f"latency: {data.get('latency_ms')} ms")
print(f"Treffer: {len(results)}")
print()
for i, hit in enumerate(results, start=1):
nid = hit.get("note_id")
cid = hit.get("node_id")
tot = hit.get("total_score")
sem = hit.get("semantic_score")
edge = hit.get("edge_bonus")
cen = hit.get("centrality_bonus")
src = hit.get("source") or {}
path = src.get("path")
sec = src.get("section")
print(f"[{i}] note_id={nid} node_id={cid}")
try:
print(
f" total={float(tot):.4f} "
f"(semantic={float(sem):.4f} edge={float(edge):.4f} centrality={float(cen):.4f})"
)
except Exception:
print(f" total={tot}, semantic={sem}, edge={edge}, centrality={cen}")
if path or sec:
print(f" source: {path or '-'} :: {sec or '-'}")
print()
return 0
if __name__ == "__main__":
raise SystemExit(main())
+48
View File
@@ -0,0 +1,48 @@
from app.core import retriever as r
from app.models.dto import QueryRequest
import app.core.qdrant as qdr
import app.core.qdrant_points as qp
import app.services.embeddings_client as ec
class _DummyClient:
pass
def _fake_get_client(cfg):
return _DummyClient()
def _fake_embed_text(text: str):
# Dimension egal, da wir search_chunks_by_vector faken
return [0.0] * 384
def _fake_search_chunks_by_vector_weights(client, prefix, vector, top=10, filters=None):
# Zwei Treffer mit unterschiedlichem retriever_weight
return [
("chunk:low", 0.9, {"note_id": "note:low", "path": "low.md", "section_title": "S1", "retriever_weight": 0.2}),
("chunk:high", 0.8, {"note_id": "note:high", "path": "high.md", "section_title": "S2", "retriever_weight": 1.5}),
]
def test_retriever_weight_influences_ranking(monkeypatch):
# Konfiguration: Qdrant & Embedding faken
monkeypatch.setattr(qdr, "get_client", _fake_get_client)
monkeypatch.setattr(ec, "embed_text", _fake_embed_text)
monkeypatch.setattr(qp, "search_chunks_by_vector", _fake_search_chunks_by_vector_weights)
req = QueryRequest(mode="semantic", query="karate", top_k=2)
resp = r.semantic_retrieve(req)
assert len(resp.results) == 2
first = resp.results[0]
second = resp.results[1]
# Semantic Scores: 0.9 (low), 0.8 (high)
# Total Scores: 0.9 * 0.2 = 0.18 vs. 0.8 * 1.5 = 1.2 -> high sollte oben liegen
assert first.note_id == "note:high"
assert second.note_id == "note:low"
assert first.total_score > second.total_score