Compare commits

...
Author SHA1 Message Date
Lars 5d5de06290 scripts/verify_chunk_texts.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 15:58:12 +02:00
Lars d7e5f398f0 scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 12:40:54 +02:00
Lars 5bf5316af5 app/core/note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 12:40:23 +02:00
Lars d9fd6d8a8f docs/knowledge_design.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 12:29:55 +02:00
Lars e672eade8b docs/knowledge_design.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 12:22:26 +02:00
Lars ec346905ed docs/chunking_strategy.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 12:22:04 +02:00
Lars c9cbbbfcb9 docs/knowledge_design.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 11:57:34 +02:00
Lars 93739935b7 docs/knowledge_design.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 11:56:54 +02:00
Lars 6a293e842e docs/chunking_strategy.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 11:56:26 +02:00
Lars f4abb1d873 scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 11:52:16 +02:00
Lars 8f48701ea0 app/core/qdrant.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 11:51:52 +02:00
Lars 6f32c60c47 app/core/edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 11:51:28 +02:00
7 changed files with 1025 additions and 627 deletions

No files matched your search

+108 -33
View File
@@ -1,45 +1,120 @@
from __future__ import annotations
from typing import List, Dict
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Modul: app/core/edges.py
Version: 1.0.0
Datum: 2025-09-09
def deriv_edges_for_note(note_meta: Dict, chunk_payloads: List[Dict]) -> List[Dict]:
Zweck
-----
Zentrale, konsistente Erzeugung von Edge-Payloads im **neuen Schema**:
- kind : "belongs_to" | "next" | "prev" | "references" | "backlink"
- source_id : ID des Quellknotens (Chunk- oder Note-ID)
- target_id : ID des Zielknotens
- scope : "chunk" | "note"
- note_id : Owner-Note (für performantes Filtern/Löschen)
- seq : optional (z. B. Reihenfolge von Vorkommen)
Hinweise
--------
- Edges werden dedupliziert (key=(kind,source_id,target_id,scope)).
- Für Chunk-Edges wird `note_id` aus dem Chunk-Payload entnommen.
- Für Note-Scope-Edges ist `note_id` die Quell-Note-ID.
"""
from __future__ import annotations
from typing import Dict, List
def build_edges_for_note(
note_id: str,
chunk_payloads: List[Dict],
note_level_refs: List[str] | None,
*,
include_note_scope_refs: bool = False,
) -> List[Dict]:
edges: List[Dict] = []
# Chunk → Note (belongs_to) + prev/next
for idx, ch in enumerate(chunk_payloads):
# Chunk-Scope: belongs_to / prev / next / references
for ch in chunk_payloads:
cid = ch["id"]
owner = ch.get("note_id") or note_id
# belongs_to
edges.append({
"src_id": ch["id"], "dst_id": note_meta["id"],
"edge_type": "belongs_to", "scope": "chunk"
"kind": "belongs_to",
"source_id": cid,
"target_id": note_id,
"scope": "chunk",
"note_id": owner,
})
prev_id = ch.get("neighbors",{}).get("prev")
next_id = ch.get("neighbors",{}).get("next")
# Nachbarn
nb = ch.get("neighbors") or {}
prev_id = nb.get("prev")
next_id = nb.get("next")
if prev_id:
edges.append({"src_id": ch["id"], "dst_id": prev_id, "edge_type": "next", "scope": "chunk"})
edges.append({"src_id": prev_id, "dst_id": ch["id"], "edge_type": "prev", "scope": "chunk"})
edges.append({
"kind": "prev",
"source_id": cid,
"target_id": prev_id,
"scope": "chunk",
"note_id": owner,
})
edges.append({
"kind": "next",
"source_id": prev_id,
"target_id": cid,
"scope": "chunk",
"note_id": owner,
})
if next_id:
edges.append({"src_id": ch["id"], "dst_id": next_id, "edge_type": "next", "scope": "chunk"})
edges.append({"src_id": next_id, "dst_id": ch["id"], "edge_type": "prev", "scope": "chunk"})
# references aus wikilinks (Chunk-Scope)
for ref in ch.get("references", []):
edges.append({
"kind": "next",
"source_id": cid,
"target_id": next_id,
"scope": "chunk",
"note_id": owner,
})
edges.append({
"kind": "prev",
"source_id": next_id,
"target_id": cid,
"scope": "chunk",
"note_id": owner,
})
# references aus Chunk
for ref in (ch.get("references") or []):
tid = ref.get("target_id")
if not tid: continue
edges.append({"src_id": ch["id"], "dst_id": tid, "edge_type": "references", "scope": "chunk"})
edges.append({"src_id": tid, "dst_id": ch["id"], "edge_type": "backlink", "scope": "chunk"})
if not tid:
continue
edges.append({
"kind": "references",
"source_id": cid,
"target_id": tid,
"scope": "chunk",
"note_id": owner,
})
# depends_on / assigned_to (Note-Scope, aus Frontmatter)
for dep in note_meta.get("depends_on", []) or []:
edges.append({"src_id": note_meta["id"], "dst_id": dep, "edge_type": "depends_on", "scope": "note"})
for ass in note_meta.get("assigned_to", []) or []:
edges.append({"src_id": note_meta["id"], "dst_id": ass, "edge_type": "assigned_to", "scope": "note"})
# Note-Level references (optional: falls du im Note-Payload `references` sammelst)
for tid in note_meta.get("references", []) or []:
edges.append({"src_id": note_meta["id"], "dst_id": tid, "edge_type": "references", "scope": "note"})
edges.append({"src_id": tid, "dst_id": note_meta["id"], "edge_type": "backlink", "scope": "note"})
# Note-Scope: backlink (immer); references (optional)
unique_refs = list(dict.fromkeys(note_level_refs or []))
for tid in unique_refs:
if include_note_scope_refs:
edges.append({
"kind": "references",
"source_id": note_id,
"target_id": tid,
"scope": "note",
"note_id": note_id,
})
edges.append({
"kind": "backlink",
"source_id": tid,
"target_id": note_id,
"scope": "note",
"note_id": note_id,
})
# Dedupe
uniq = {}
dedup = {}
for e in edges:
k = (e["src_id"], e["edge_type"], e["dst_id"], e.get("scope","note"))
uniq[k] = e
return list(uniq.values())
k = (e["kind"], e["source_id"], e["target_id"], e.get("scope", ""))
dedup[k] = e
return list(dedup.values())
+130 -35
View File
@@ -2,7 +2,7 @@
# -*- coding: utf-8 -*-
"""
Modul: app/core/note_payload.py
Version: 1.4.0
Version: 1.5.1
Datum: 2025-09-09
Kurzbeschreibung
@@ -12,18 +12,36 @@ Idempotenz wird der vollständige Body unter ``fulltext`` persistiert und
der Dateipfad relativ zum Vault gespeichert. Das erlaubt eine verlustfreie
Rekonstruktion im Export (erst ``fulltext``, sonst Chunks).
Wichtig
-------
- **Nur Inhalte** gehen in den Hash: Weder Dateisystem-Zeitstempel (mtime/ctime)
noch sonstige FS-Metadaten werden berücksichtigt.
- Hash-Quelle: Parser-Body (Default) oder Rohdatei-Body (Frontmatter via Regex entfernt).
Änderungen in v1.5.1
--------------------
- Neue Env-Var **MINDNET_HASH_COMPARE** als Synonym zu MINDNET_HASH_MODE.
- Akzeptiert komfortable Werte (case-insensitive): **Body**, **Frontmatter**, **Full**.
*Full* wird intern zu ``body+frontmatter`` normalisiert.
- CLI akzeptiert weiterhin ``--hash-mode``; Importer reicht diese Einstellung durch.
Hash-Steuerung
--------------
- Modus: ``body`` (Default) | ``frontmatter`` | ``body+frontmatter``
* per Funktionsparameter ``hash_mode`` (prio 1)
* oder ENV ``MINDNET_HASH_MODE`` (prio 2)
- Normalisierung: ``canonical`` (Default) | ``none``
* per Funktionsparameter ``hash_normalize`` (prio 1)
* oder ENV ``MINDNET_HASH_NORMALIZE`` (prio 2)
- Modus (welche Teile in den Hash einfließen):
* ``body`` (Default)
* ``frontmatter``
* ``body+frontmatter`` (Synonym CLI/ENV: ``full``)
Quelle:
* Funktionsparameter ``hash_mode`` (höchste Priorität)
* Env ``MINDNET_HASH_MODE`` oder **``MINDNET_HASH_COMPARE``** (Fallback)
Normalisierung:
* ``canonical`` (Default) | ``none`` — via Param ``hash_normalize`` oder Env ``MINDNET_HASH_NORMALIZE``
Quelle des Body-Textes:
* ``parsed`` (Default) | ``raw`` — via Param ``hash_source`` oder Env ``MINDNET_HASH_SOURCE``
Beispiele (CLI – Sichtprüfung)
------------------------------
python3 -m app.core.note_payload --from-file ./vault/demo.md --vault-root ./vault --print
CLI (Sichtprüfung)
------------------
python3 -m app.core.note_payload --from-file ./vault/demo.md --vault-root ./vault --print --hash-source raw
"""
from __future__ import annotations
@@ -31,16 +49,16 @@ import argparse
import hashlib
import json
import os
from typing import Any, Dict, Optional
from typing import Any, Dict, Optional, Tuple
try:
from app.core.parser import read_markdown, extract_wikilinks
from app.core.parser import read_markdown, extract_wikilinks, FRONTMATTER_RE
except Exception: # pragma: no cover
from .parser import read_markdown, extract_wikilinks # type: ignore
from .parser import read_markdown, extract_wikilinks, FRONTMATTER_RE # type: ignore
# ---------------------------------------------------------------------------
# Hashing
# Helpers
# ---------------------------------------------------------------------------
def _canon_frontmatter(fm: Dict[str, Any]) -> str:
@@ -51,13 +69,62 @@ def _normalize_body(body: str, mode: str) -> str:
"""Normalisiert den Body für reproduzierbare Hashes (oder nicht)."""
if mode == "none":
return body if body is not None else ""
# canonical: \r\n→\n, trailing spaces, mehrfach-blankzeilen trimmen
# canonical: \r\n→\n, trailing spaces entfernen
text = (body or "").replace("\r\n", "\n").replace("\r", "\n")
# trailing whitespace am Zeilenende entfernen
text = "\n".join(line.rstrip() for line in text.split("\n"))
# keine aggressivere Logik (keine inhaltliche Änderung)
return text
def _resolve_hash_mode(explicit: Optional[str]) -> str:
"""
Normalisiert den Hash-Modus auf einen der Werte:
'body' | 'frontmatter' | 'body+frontmatter'
Akzeptiert auch 'full' als Alias für 'body+frontmatter'.
Beachtet zusätzlich die Env-Variablen MINDNET_HASH_MODE und MINDNET_HASH_COMPARE.
"""
if explicit:
val = explicit.strip().lower()
else:
val = (os.environ.get("MINDNET_HASH_MODE") or os.environ.get("MINDNET_HASH_COMPARE") or "body").strip().lower()
if val in ("full", "fulltext", "body+frontmatter", "bodyplusfrontmatter"):
return "body+frontmatter"
if val in ("frontmatter", "fm"):
return "frontmatter"
# default & fallbacks
return "body"
def _read_raw_body_from_file(file_path: Optional[str]) -> Tuple[str, Dict[str, Any]]:
"""Liest die Rohdatei und extrahiert Body & Frontmatter ohne Parser-Logik.
Rückgabe:
(body_text, frontmatter_dict)
"""
if not file_path or not os.path.exists(file_path):
return "", {}
try:
with open(file_path, "r", encoding="utf-8") as f:
raw = f.read()
except Exception:
return "", {}
# Frontmatter per Regex entfernen
m = FRONTMATTER_RE.match(raw)
fm = {}
if m:
fm_txt = m.group(1)
try:
import yaml # lazy
fm = yaml.safe_load(fm_txt) or {}
except Exception:
fm = {}
body = raw[m.end():]
else:
body = raw
return body, fm
# ---------------------------------------------------------------------------
# Hashing
# ---------------------------------------------------------------------------
def compute_hash(
*,
body: Optional[str],
@@ -76,7 +143,7 @@ def compute_hash(
- "canonical" (Default)
- "none"
"""
mode = (mode or os.environ.get("MINDNET_HASH_MODE", "body")).strip().lower()
mode = _resolve_hash_mode(mode)
normalize = (normalize or os.environ.get("MINDNET_HASH_NORMALIZE", "canonical")).strip().lower()
body = _normalize_body(body or "", normalize)
@@ -104,6 +171,8 @@ def make_note_payload(
*,
hash_mode: Optional[str] = None,
hash_normalize: Optional[str] = None,
hash_source: Optional[str] = None,
file_path: Optional[str] = None,
) -> Dict[str, Any]:
"""
Erzeugt den Payload für eine geparste Note.
@@ -115,9 +184,13 @@ def make_note_payload(
vault_root : Optional[str]
Vault-Wurzel (für Pfad-Relativierung). Wenn ``None``, wird ``path`` unverändert übernommen.
hash_mode : Optional[str]
"body" | "frontmatter" | "body+frontmatter" (überschreibt ENV).
"body" | "frontmatter" | "body+frontmatter" | "full" (Alias; überschreibt ENV).
hash_normalize : Optional[str]
"canonical" | "none" (überschreibt ENV).
hash_source : Optional[str]
"parsed" (Default) oder "raw". Wenn "raw", wird der Body aus der Rohdatei gelesen.
file_path : Optional[str]
Pfad zur Markdown-Datei, erforderlich für ``hash_source=raw``.
Returns
-------
@@ -125,17 +198,30 @@ def make_note_payload(
Qdrant-Payload für die Notes-Collection.
"""
# "Duck typing": dict oder Objekt akzeptieren
fm = (
getattr(parsed, "frontmatter", None)
or getattr(parsed, "fm", None)
or getattr(parsed, "front_matter", None)
or (parsed.get("frontmatter") if isinstance(parsed, dict) else {})
) or {}
body = getattr(parsed, "body", None) or (parsed.get("body") if isinstance(parsed, dict) else "") or ""
path = getattr(parsed, "path", None) or (parsed.get("path") if isinstance(parsed, dict) else "") or ""
if isinstance(parsed, dict):
fm = parsed.get("frontmatter") or {}
body = parsed.get("body") or ""
path = parsed.get("path") or ""
else:
fm = getattr(parsed, "frontmatter", {}) or {}
body = getattr(parsed, "body", "") or ""
path = getattr(parsed, "path", "") or ""
# Hash gem. Modus bilden
hash_fulltext = compute_hash(body=body, frontmatter=fm, mode=hash_mode, normalize=hash_normalize)
# Hash-Quelle bestimmen
src = (hash_source or os.environ.get("MINDNET_HASH_SOURCE", "parsed")).strip().lower()
raw_body, raw_fm = ("", {})
if src == "raw":
raw_body, raw_fm = _read_raw_body_from_file(file_path or path)
# Roh-FM ergänzen (nicht überschreiben)
if isinstance(raw_fm, dict) and raw_fm:
merged_fm = dict(fm)
for k, v in raw_fm.items():
merged_fm.setdefault(k, v)
fm = merged_fm
# Hash gemäß Modus/Quelle bilden
body_for_hash = raw_body if src == "raw" else body
hash_fulltext = compute_hash(body=body_for_hash, frontmatter=fm, mode=hash_mode, normalize=hash_normalize)
# Pfad relativieren
rel_path = path
@@ -145,9 +231,9 @@ def make_note_payload(
rel = rel.replace("\\", "/").lstrip("/") # normalisieren
rel_path = rel
except Exception:
pass # Pfad nicht kritisch für Hash/ID
pass # Pfad ist nicht kritisch für Hash/ID
# Optionale Note-Level-Wikilinks (Fallback, wenn Chunks nicht geliefert werden)
# Note-Level-Wikilinks (Fallback, wenn Chunks nicht geliefert werden)
note_level_refs = list(dict.fromkeys(extract_wikilinks(body))) if body else []
payload: Dict[str, Any] = {
@@ -160,16 +246,23 @@ def make_note_payload(
"path": rel_path or fm.get("path"),
"tags": fm.get("tags"),
"hash_fulltext": hash_fulltext,
# Volltext persistieren (verlustfreie Rekonstruktion)
# Volltext persistieren (verlustfreie Rekonstruktion) – aus PARSED-Body
"fulltext": body,
# Fallback-Refs auf Note-Ebene
"references": note_level_refs,
}
for k in ("area", "project", "source", "lang", "slug"):
for k in ("area", "project", "source", "lang", "slug", "aliases"):
if k in fm:
payload[k] = fm[k]
# Optional: Roh-Body-Hash zusätzlich persistieren
if os.environ.get("MINDNET_HASH_STORE_RAW", "false").strip().lower() == "true" and src == "raw":
try:
payload["hash_raw_body"] = compute_hash(body=raw_body, frontmatter=fm, mode="body", normalize="none")
except Exception:
pass
return payload
@@ -182,13 +275,15 @@ def _cli() -> None:
ap.add_argument("--from-file", dest="src", required=True, help="Pfad zur Markdown-Datei")
ap.add_argument("--vault-root", dest="vault_root", default=None, help="Vault-Wurzel zur Pfad-Relativierung")
ap.add_argument("--print", dest="do_print", action="store_true", help="Payload auf stdout ausgeben")
ap.add_argument("--hash-mode", choices=["body", "frontmatter", "body+frontmatter"], default=None)
ap.add_argument("--hash-mode", choices=["body", "frontmatter", "body+frontmatter", "full"], default=None)
ap.add_argument("--hash-normalize", choices=["canonical", "none"], default=None)
ap.add_argument("--hash-source", choices=["parsed", "raw"], default=None)
args = ap.parse_args()
parsed = read_markdown(args.src)
payload = make_note_payload(parsed, vault_root=args.vault_root,
hash_mode=args.hash_mode, hash_normalize=args.hash_normalize)
hash_mode=args.hash_mode, hash_normalize=args.hash_normalize,
hash_source=args.hash_source, file_path=args.src)
if args.do_print:
print(json.dumps(payload, ensure_ascii=False, indent=2))
+31 -59
View File
@@ -2,30 +2,16 @@
# -*- coding: utf-8 -*-
"""
Name: app/core/qdrant.py
Version: v1.3.1 (2025-09-05)
Version: v1.4.0 (2025-09-09)
Kurzbeschreibung:
Qdrant-Client & Collection-Setup für mindnet.
- Stellt sicher, dass {prefix}_notes / {prefix}_chunks / {prefix}_edges existieren.
- Edges-Collection nutzt 1D Dummy-Vektor (Workaround für Python-Client).
- **Nicht-destruktiv per Default**: ensure_collections(..., destructive=False).
- **Abwärtskompatibel**: collection_names(prefix) wieder verfügbar.
- Edges-Collection nutzt 1D Dummy-Vektor.
- NEW: ensure_payload_indexes(...) legt sinnvolle Payload-Indizes an.
Aufruf/Verwendung:
from app.core.qdrant import QdrantConfig, get_client, ensure_collections, collection_names
Umgebungsvariablen (optional):
QDRANT_URL | QDRANT_HOST/QDRANT_PORT, QDRANT_API_KEY,
COLLECTION_PREFIX (Default "mindnet"), VECTOR_DIM (Default 384)
Änderungen:
v1.3.1: Helper collection_names(prefix) wiederhergestellt (für reset_qdrant usw.).
v1.3.0: ensure_collections(..., destructive=False) – keine stillen Drops im Dry-Run.
Edges-Collection nur bei explicit destructive=True neu anlegen.
≤v1.2.x: Konnte {prefix}_edges bei fehlender VectorConfig automatisch neu erstellen (riskant).
Bezug/Quelle:
Alte Core-Variante enthielt collection_names(prefix); diverse Scripts nutzen das weiterhin. :contentReference[oaicite:1]{index=1}
Aufruf:
from app.core.qdrant import QdrantConfig, get_client, ensure_collections, ensure_payload_indexes
"""
from __future__ import annotations
import os
@@ -36,10 +22,6 @@ from qdrant_client import QdrantClient
from qdrant_client.http import models as rest
# -------------------------------
# Konfiguration
# -------------------------------
@dataclass
class QdrantConfig:
url: str
@@ -60,18 +42,10 @@ class QdrantConfig:
return QdrantConfig(url=url, api_key=api_key, prefix=prefix, dim=dim)
# -------------------------------
# Client
# -------------------------------
def get_client(cfg: QdrantConfig) -> QdrantClient:
return QdrantClient(url=cfg.url, api_key=cfg.api_key)
# -------------------------------
# Collection-Erzeuger (Hilfsfunktionen)
# -------------------------------
def _create_notes(client: QdrantClient, name: str, dim: int) -> None:
if not client.collection_exists(name):
client.create_collection(
@@ -94,16 +68,7 @@ def _create_edges(client: QdrantClient, name: str) -> None:
)
# -------------------------------
# Public API
# -------------------------------
def ensure_collections(client: QdrantClient, prefix: str, dim: int, destructive: bool = False) -> None:
"""
Stellt sicher, dass die drei Collections existieren.
- Default **nicht destruktiv**: vorhandene Collections bleiben unangetastet.
- Nur wenn 'destructive=True', wird eine ungeeignete Edges-Collection gelöscht und neu angelegt.
"""
notes = f"{prefix}_notes"
chunks = f"{prefix}_chunks"
edges = f"{prefix}_edges"
@@ -112,41 +77,48 @@ def ensure_collections(client: QdrantClient, prefix: str, dim: int, destructive:
_create_chunks(client, chunks, dim)
if client.collection_exists(edges):
# Prüfen, ob die Edges-Collection bereits eine Vektorkonfig hat
try:
info = client.get_collection(edges)
vectors_cfg = getattr(getattr(info.result, "config", None), "params", None)
has_vectors = getattr(vectors_cfg, "vectors", None) is not None
except Exception:
# konservativ: nichts anfassen, um Datenverlust zu vermeiden
has_vectors = True
if not has_vectors:
if destructive:
client.delete_collection(edges)
_create_edges(client, edges)
else:
print(
f"[ensure_collections] WARN: '{edges}' ohne VectorConfig gefunden; "
f"keine destruktive Änderung (destructive=False).",
flush=True,
)
print(f"[ensure_collections] WARN: '{edges}' ohne VectorConfig; destructive=False.", flush=True)
else:
_create_edges(client, edges)
def collection_names(prefix: str) -> Tuple[str, str, str]:
"""
Abwärtskompatibler Helper für Scripts:
returns (f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges")
"""
return (f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges")
def wipe_collections(client: QdrantClient, prefix: str) -> None:
"""
Löscht alle drei Collections – nur verwenden, wenn bewusst ein Clean-Rebuild gewünscht ist.
"""
for name in collection_names(prefix):
if client.collection_exists(name):
client.delete_collection(name)
# -------------------------------
# NEW: Payload-Indexing
# -------------------------------
def _safe_create_index(client: QdrantClient, col: str, field: str, schema: rest.PayloadSchemaType):
try:
client.create_payload_index(
collection_name=col,
field_name=field,
field_schema=schema,
)
except Exception:
# bereits vorhanden oder nicht unterstütztes Schema → ignorieren
pass
def ensure_payload_indexes(client: QdrantClient, prefix: str) -> None:
notes, chunks, edges = collection_names(prefix)
# Notes
_safe_create_index(client, notes, "note_id", rest.PayloadSchemaType.KEYWORD)
# Chunks
_safe_create_index(client, chunks, "note_id", rest.PayloadSchemaType.KEYWORD)
_safe_create_index(client, chunks, "chunk_index", rest.PayloadSchemaType.INTEGER)
# Edges
for f in ("kind", "scope", "source_id", "target_id", "note_id"):
_safe_create_index(client, edges, f, rest.PayloadSchemaType.KEYWORD)
+106 -116
View File
@@ -13,74 +13,67 @@ Entwickle eine robuste, parser-freundliche **Chunking-Strategie** für Markdown-
---
## 2) Annahmen aus `knowledge_design.md`
- **Stabile IDs** & Dateinamen-Schema (z. B. `YYYYMMDD-HHMM-type-slug` bzw. `type-slug`).
- **Pflichtfelder** in YAML: `title`, `id`, `type`, `status`, `created`, `tags` (empfohlene Felder ggf. mehr).
- **Abschnitts-Konventionen** je `type` (z. B. `## Zusammenfassung`, `## Kontext` …) → ideale **Chunk-Grenzen**.
- **Edge-Typen**: `belongs_to`, `references`, `backlink`, `depends_on`, `assigned_to`, `discussed_in`, `authored_by`, `related`. Für Chunking primär `belongs_to` & `references` (+ optionale `prev`/`next`).
- **IDs**: deterministische, stabile `id` pro Note (Slug / semantischer Identifier), ggf. `aliases`.
- **Dateinamen**: entweder `YYYY-MM-DD_title.md` oder `slug.md`; Pfade sind **relativ** zum Vault.
- **Frontmatter-Pflichtfelder**: `id`, `title`, `type`, `created`, `updated` (Details in `knowledge_design.md`).
- **Backlink-/Link-Regeln**: Wikilinks `[[id]]` im Body; am Ende optional redaktionelle Sektion „Mögliche Verbindungen“ (erzeugt **keine** Kanten).
---
## 3) Chunking-Prinzipien
1. **Frontmatter extrahieren** → als strukturiertes `metadata` (nicht in `text` des Chunks).
2. **Markdown AST** (oder strukturierter Parser) nutzen:
- Primäre Grenzen: **Überschriftenebene H2/H3** (H1 = Dokumenttitel).
- Sekundär: **Absätze**, **nummerierte/unnummerierte Listen** als atomare Einheiten, **Codeblöcke** als zusammenhängender Block (nicht splitten).
3. **Längensteuerung**: Semantik vor harter Länge. Wenn Abschnitt > Zielgröße, **weich segmentieren** entlang von Absätzen/Listenpunkten.
4. **Referenz-Extraktion**: `[[Wikilinks]]` + Markdown-Links → `references`. Backlinks werden downstream generiert.
5. **Kontext-Overlap**: Chunks erhalten **Überlappung** über Satz-/Absatzgrenzen, um Kohärenz beim Retrieval zu erhöhen.
- **Semantische Schnitte**: Chunks enden an Absätzen, Überschriften, Listenpunkten, Codeblöcken, Zitaten.
- **Frontmatter**: YAML **nicht** embedden; stattdessen komplett im Note-Payload speichern.
- **Verlustfreiheit**:
- Note-Payload: `fulltext` (gesamter Body).
- Chunk-Payload: `text` (Originalchunk).
Damit kann der Export den Body **verlustfrei** rekonstruieren (erst `fulltext`, sonst Chunks).
---
## 4) Optimale Chunkgrößen & Overlaps
> Ziel: gutes Recall@k, wenig Fragmentierung, stabile Antwortqualität.
- **Zielgröße**: 250–400 Tokens (Richtwert, abhängig vom `type`).
- **Maxgröße**: 600–800 Tokens (nur in Ausnahmen).
- **Mingröße**: 80–120 Tokens (sonst mit Nachbar verschmelzen).
- **Overlap**: 40–60 Tokens, um Kontextverlust zu vermeiden.
- **Kontextabhängig**:
- `concept`, `thought`, `experience`: 250–350 Tokens
- `task`, `project`: eher 200–300 Tokens (mehr Bullet-Struktur)
- `journal`: 300–400 Tokens (tagesabschnittsweise)
| Notiz-Typ (`type`) | Inhalt | Zielgröße (Tokens) | Max. Größe (Tokens) | Overlap (Tokens) | Hinweise |
|---|---|---:|---:|---:|---|
| `thought` | kurze Thesen/Ideen | 150–250 | 300 | 30–40 | meist 1–2 Chunks |
| `experience` | Kontext/Beobachtung/Interpretation | 250–350 | 450 | 40–60 | Trenne entlang der Template-Sektionen |
| `journal` | Tagebuch, episodisch | 200–300 | 400 | 30–50 | Tagesabschnitte bündeln |
| `task` | knapp, Checklisten | 120–200 | 250 | 20–30 | Listen nicht splitten |
| `project` | Scope/WPs/Risiken/Status | 300–450 | 600 | 50–70 | Pro Hauptsektion ein Chunk |
| `concept` | definierte Begriffe, Erklärungen | 250–400 | 550 | 40–60 | Definition separat halten |
| `source` | Metadaten + Auszüge/Notizen | 200–350 | 500 | 30–50 | Zitate als eigene Chunks (Urheberrecht) |
---
## 4.1 Overlap-Regeln
- Overlap **nie mitten im Satz** beenden → mindestens **ein kompletter Satz** wandert in den nächsten Chunk.
- An **Absatzgrenzen** ausrichten, wenn möglich.
- Bei **Listen** ggf. den vorherigen Punkt als Overlap mitführen (falls < 50 Tokens).
- Codeblöcke und Tabellen **nicht splitten**; wenn sie größer als `Max-Tokens` sind, als **eigener Chunk** belassen (Ausnahmefall zulassen).
**Daumenregel (zeichenzentriert):** ~4 Zeichen ≈ 1 Token → 800–1600 Zeichen Ziel; Overlap ~120–240 Zeichen (≈ 30–60 Tokens).
**Mindestanforderung:** Keine Trennung innerhalb von Sätzen. Sicherstellung, dass immer an Satzenden gechunct wird
**Default für mindnet:** **~300 Tokens** + **~50 Tokens Overlap**; per `type` feinjustieren (siehe Tabelle).
- Overlap betrifft **nur den Body**; die YAML-Frontmatter bleibt **außerhalb**.
- Keine Overlaps, die Codeblöcke oder Tabellen „aufreißen“. Falls nötig: Chunk-Grenze an Blockgrenze ziehen.
- Bei reinen Listen: zusammenhängende Bullets gruppieren, ggf. kleinere Overlaps.
---
## 5) Semantische Regeln je Strukturelement
- **Überschriften (H2/H3)**: new chunk start; speichere `section_path` (z. B. `/Kontext/Beobachtung`).
- **Absätze**: Primäre Untereinheiten; wenn Zusammenfassung + Beispiel direkt folgen, zusammen lassen.
- **Listen**: Jeder **Listeneintrag** bleibt zusammen mit seinem einleitenden Satz (falls vorhanden). Große Listen → in **logische Blöcke** (5–8 Items) splitten.
- **Codeblöcke**: Nicht splitten; ggf. separater Chunk, **aber** im Retrieval **downweighten** (optional).
- **Zitate/Blockquotes**: zusammenhalten; Quelle im `references_meta` anreichern (falls Link vorhanden).
- **Tabellen**: als ein Chunk; zusätzlich **Plain-Text-Extrakt** (Header + 1–2 Zeilen) in `summary` für Retriever, falls Modelle Tabellen schlechter verarbeiten.
- **Überschriften**: vorzugsweise an H2/H3 trennen; H1 meist Dokumenttitel → Teil der Frontmatter.
- **Absätze**: primäre Trennkandidaten.
- **Listen**: zusammenhängende Gruppe als ein Chunk, wenn sie einen semantischen Block bilden.
- **Codeblöcke**: niemals splitten; Code bleibt in einem Chunk.
- **Zitate**: ab 2+ Zeilen als eigener Chunk.
- **Bilder/Anhänge**: Referenzen im Text belassen; Pfade relativ halten.
---
## 6) Normalisierung & Preprocessing
- **Nicht embedden:** YAML-Frontmatter (aber spezifische Felder als `metadata.*` mitschreiben: `type`, `tags`, `area`, `project`, `priority`, `people`, `aliases`).
- **Bereinigen:** führende/trailing Spaces, Mehrfach-Leerzeilen → 1; Unicode-NFKC; Zeilenenden normalisieren.
- **Bewahren:** Markdown-Semantik (Überschriften-Hashes, Listenpräfixe, Codefences) **im Text beibehalten**, damit RAG-Antworten sauber zitieren können.
- **Sprachhinweis:** `lang` heuristisch bestimmen (DE/EN/…); in `metadata.lang` ablegen → später für sprachspezifische Embeddings nützlich.
- **Stop-Abschnitte:** „Mögliche Verbindungen“ am Ende **separat** chunken (nur Links), um Link-Graph sauber zu extrahieren.
- **Zeilenenden**: `\r\n` → `\n`, trailing spaces trimmen (nur für Hashing, nicht für Anzeige).
- **Whitespace**: mehrfach-Blankzeilen reduzieren (optional, Hash-Modus beachten).
- **Links**: `[[Titel|id]]` zu `(display="Titel", target_id="id")` normalisieren.
- **Pfade**: `path` im Payload **zwingend relativ** (Backslashes → Slashes).
---
## 7) Edge-Modell (Graph)
- **Chunk → Note:** `belongs_to(note_id)` (obligatorisch).
- **Chunk → Chunk (gleiche Note):** `prev`, `next` (lineare Leserichtung).
- **Note/Chunk → Note:** `references(target_id)` aus `[[Wikilinks]]` & Markdown-Links; optional `related` (schwach).
- **Backlink:** systemisch generiert: inverse Kante `backlink`.
- **Sektionen:** `has_section(note_id, section_path)` (optional, für Navigations-UI).
- **Task-Spezialfälle:** `depends_on`, `assigned_to(person-id)` bleiben **Note-Level** (nicht Chunk-Level).
- **Chunk → Note:** `belongs_to(note_id)` (obligatorisch; Edge-Payload enthält zusätzlich `note_id` als Owner-Note).
- **Chunk → Chunk (gleiche Note):** `prev`, `next` (symmetrisch für lineare Navigation; beide Richtungen werden erzeugt).
- **Chunk → Note:** `references(target_id)` aus `[[Wikilinks]]` oder Markdown-Links im Chunk-Text (Standard; *Chunk-Scope*).
- **Note → Note:** `backlink(target_id)` automatisch generiert, dedupliziert pro Note (*Note-Scope*).
- **Optional:** `references:note` (Note-Scope-References) per Flag/ENV aktivierbar; **Default = aus**, um Doppelzählungen zu vermeiden.
- **Unresolved:** Wenn `target_id` nicht existiert, wird eine Kante mit `status: "unresolved"` angelegt (später durch Resolver/Agent heilbar).
---
@@ -100,26 +93,49 @@ Entwickle eine robuste, parser-freundliche **Chunking-Strategie** für Markdown-
"project": "project-mindnet",
"tags": ["area/mindnet","type/thought","topic/yaml"],
"chunk_index": 2,
"char_start": 1240,
"char_end": 2012,
"token_count": 305,
"char_start": 1024,
"char_end": 1789,
"section_title": "Begründung / Details",
"section_path": "/Begründung / Details",
"lang": "de",
"wikilinks": ["concept-vektorsuche-qdrant","source-obsidian-properties"],
"external_links": [],
"references": [
{"target_id": "concept-vektorsuche-qdrant", "kind": "wikilink"}
],
"neighbors": {"prev": "#c01", "next": "#c03"},
"created_at": "2025-09-02T18:35:00+02:00"
"section_path": "Begründung / Details",
"neighbors": {"prev": "…#c01", "next": "…#c03"},
"wikilinks": ["concept-yaml-styleguide"],
"references": [{"kind":"wikilink", "target_id":"concept-yaml-styleguide"}],
"text": "… ursprünglicher Chunk-Text …"
}
}
**Collection-Einstellungen (Empfehlung)**
- `distance`: `Cosine` (gemischte Textlängen)
- `vectors`: 384–1024 Dim (abh. Embedding-Modell)
- `hnsw_ef_construct`: 128–256; `m`: 16–32 (Workload-abhängig)
**Point (Note)**
{
"id": "20250902-1830-thought-yaml-recall",
"vector": [/* optional Nullvektor oder Zentroid */],
"payload": {
"note_id": "20250902-1830-thought-yaml-recall",
"title": "Gedanke: Einheitliche YAML-Standards steigern Recall",
"type": "thought",
"status": "draft",
"created": "2025-09-02",
"updated": "2025-09-02",
"path": "10_thoughts/20250902-1830-thought-yaml-recall.md",
"tags": ["area/mindnet","type/thought","topic/yaml"],
"hash_fulltext": "sha256:…",
"fulltext": "… gesamter Body für verlustfreie Rekonstruktion …",
"references": ["concept-yaml-styleguide"] // Fallback für Note-Level-Backlinks
}
}
**Edges (Payload; neues Schema)**
{
"kind": "references" | "backlink" | "belongs_to" | "prev" | "next",
"source_id": "<chunk_id|note_id>",
"target_id": "<note_id|chunk_id>",
"scope": "chunk" | "note",
"note_id": "<owner-note-id>", // neu: für schnelles Filtern/Purge
"status": "ok" | "unresolved" // optional
}
**Performance-Hinweis (Qdrant):** Für schnelle Filter/Deletes Payload-Indizes anlegen: **edges** → `kind`, `scope`, `source_id`, `target_id`, `note_id`; **chunks** → `note_id`, `chunk_index`; **notes** → `note_id`.
---
@@ -136,79 +152,53 @@ Entwickle eine robuste, parser-freundliche **Chunking-Strategie** für Markdown-
blocks = group_blocks(sec, keep_code=True, keep_lists=True)
for group in soft_wrap(blocks, target_tokens=target_size(meta["type"]),
max_tokens=max_size(meta["type"])):
raw_chunks.append(render_markdown(group))
raw_chunks.append(render_md(group))
chunks = apply_overlap(raw_chunks, overlap_tokens=overlap_size(meta["type"]))
chunks = trim_whitespace(chunks)
chunks = apply_overlap(raw_chunks, overlap_tokens=overlap(meta["type"]))
chunks = normalize_chunks(chunks) # trim, fix code fences, etc.
# link extraction
for i, ch in enumerate(chunks):
ch.payload.update({
"wikilinks": extract_wikilinks(ch.text),
"external_links": extract_md_links(ch.text),
"references": [{"target_id": t, "kind": "wikilink"} for t in extract_wikilinks(ch.text)],
"neighbors": {"prev": f"#c{i-1}" if i>0 else None,
"next": f"#c{i+1}" if i<len(chunks)-1 else None}
})
# IDs & Nachbarn
for i, ch in enumerate(chunks, start=1):
ch.id = f"{meta['id']}#c{i:02d}"
ch.index = i
ch.neighbors_prev = chunks[i-2].id if i > 1 else None
ch.neighbors_next = chunks[i].id if i < len(chunks) else None
# attach metadata
for idx, ch in enumerate(chunks):
ch.id = f'{meta["id"]}#c{idx:02d}'
ch.payload |= minimal_payload_from_meta(meta, file_path, idx, ch)
# Wikilinks je Chunk
for ch in chunks:
ch.wikilinks = extract_wikilinks(ch.text)
return chunks
**Hinweise zur Implementierung**
- **Tokenizer**: gleiche Tokenizer-Funktion für **Längensteuerung** und **Embedding** nutzen (Leak vermeiden).
- **Overlap** implementieren auf **Satz-/Absatzebene**; notfalls anhand Token-Fenster (kein Wort-Cut).
- **Heuristik** für `target_size`/`overlap_size` per `type` (siehe Tabelle).
- **Später**: Re-Chunking ermöglichen (idempotente Re-Runs), Chunk-IDs stabil halten (Index + Hash über `section_path + first_64_tokens`).
---
## 10) Einbettung (Embeddings)
- **Standard:** nur `chunk.text` embedden (ohne YAML), **aber**:
- `aliases`, `title` können als **synthetischer Kontext** *vorangestellt* werden (konkateniert, durch Trennzeichen), falls Recall für Synonyme wichtig ist.
- **Mehrsprachigkeit:** pro Chunk die Sprache detektieren; ggf. **mehrsprachige Modelle**/Pipelines verwenden.
- **Code-Gewichtung:** optional zweite Vektor-Spur für Code (separate Collection) falls viel Technik.
- Modell: MiniLM/all-MiniLM-L6-v2 (384d) oder E5 (besseres Retrieval, ggf. multilingual).
- **Note-Embeddings** optional (Zentroid der Chunks).
- **Hashing für Change-Detection** (Importer):
- `MINDNET_HASH_MODE = body|frontmatter|body+frontmatter` (Default: `body`)
- `MINDNET_HASH_NORMALIZE = canonical|none` (Default: `canonical`)
---
## 11) Qualitätssicherung
- **Unit-Tests**: Gold-Notes mit erwarteten Section-Splits und Link-Graph.
- **Metrics**: Retrieval-Eval (nDCG@k, Recall@k) auf internen QA-Fragen.
- **Linting**: Pre-commit prüft Pflichtfelder & Link-Integrität (IDs, Dateinamen, Wikilinks).
- **Zähler**: `notes/chunks/edges` je Lauf prüfen.
- **Edge-Invarianten**:
- `belongs_to == #Chunks`
- `next == prev == Σ(max(chunks_in_note-1, 0))`
- `references (chunk) == Σ(Chunk-Wikilinks)`
- `backlink == Σ(eindeutige Wikilinks je Note)`
- **Unresolved**: sollten durch Resolver-Jobs über Zeit abnehmen.
- **Roundtrip-Test**: Import → Export → Diff; exakt rekonstruierbare Bodies.
---
## 12) Deliverables
1. **Python-Modul** `mindnet_chunker/` (Parser, Chunker, Link-Extractor, Qdrant-Client).
2. **CLI** `mindnet-chunk` (stdin→stdout, oder Datei→NDJSON).
3. **Docs**: README mit Schema & Beispielen; Tests + Fixtures.
- Code: Parser, Chunker, Importer, Exporter, Edges.
- Schemas: `note.schema.json`, Payload-Layouts.
- Tests: Mini-Vault (`scripts/make_test_vault.py`), Audit/Validate.
---
## 13) Prompt für neues Chatfenster (kopieren & einfügen)
**Projekt:** mindnet Wissensnetzwerk
**Rolle:** Du bist mein Assistent für NLP-Strategien.
**Ziel:** Hilf mir, eine robuste Chunking-Strategie für Markdown-Notizen zu entwickeln, die später in Qdrant gespeichert werden.
**Anforderungen:**
- Nutze das YAML-Frontmatter-Schema und die Strukturregeln aus `knowledge_design.md`. (Pflichtfelder, Abschnitts-Konventionen, Edge-Typen)
- Definiere optimale Chunkgrößen (Tokens) nach Notiz-Typ, inkl. **Overlap-Empfehlungen**.
- Beschreibe, wie **logische Abschnitte** (Überschriften/Absätze/Listen/Code) als Grenzen dienen.
- Erkläre das **Edge-Modell** zwischen **Chunks** und **Notizen** (`belongs_to`, `references`, `backlink`, `prev/next`).
- Ergebnis: ein **konkretes Konzept + Python-Outline**, das ich direkt implementieren kann (inkl. Datenmodell für Qdrant).
**Kontext zum System:**
- IDs/Dateinamen/Tags gemäß `knowledge_design.md`.
- Zielgröße pro Chunk ~**300 Tokens**, **Overlap ~50 Tokens** als Default; per `type` feinjustiert (Tabelle).
- YAML wird **nicht** in die Embeddings gemischt; ausgewählte Felder als `payload`.
Bitte liefere:
1) Zusammenfassung der Strategie,
2) Tabelle mit Größen/Overlaps,
3) Python-Pseudocode für Chunker,
4) Qdrant-Payload-Beispiel,
5) Test-Plan kurz.
*(Unverändert)*
+371 -303
View File
@@ -3,9 +3,9 @@ title: "mindnet – Knowledge Design"
id: "design-knowledge-architecture"
type: "guide"
status: "active"
version: "1.2.0"
version: "1.3.0"
created: 2025-09-02
updated: 2025-09-02
updated: 2025-09-09
tags: ["type/guide","area/mindnet","topic/obsidian","topic/knowledge-architecture"]
owner: "Ich"
---
@@ -15,422 +15,490 @@ owner: "Ich"
## 1. Gesamtziel, Anspruch & Nutzen
**Ziel:**
*mindnet* ist ein persönliches Wissensnetzwerk, das **alle** relevanten Inhalte – Gedanken, Erfahrungen, Aufgaben, Projekte, Quellen, Personen, Meetings, Tagebuch/Journal, Wendepunkte und Leitbilder – **einheitlich** in Markdown + YAML ablegt. Es bildet einen **Spiegel der Persönlichkeit** (Werte, Überzeugungen, Erlebnisse) und ist zugleich so strukturiert, dass Tools (Dataview, Embeddings, Vektorsuche/Qdrant, Agenten) es **maschinenlesbar** nutzen können.
*mindnet* ist ein persönliches Wissensnetzwerk, das **alle** relevanten Informationen über mein Leben, meine Werte, Projekte, Erfahrungen, Pläne und Erkenntnisse **strukturiert** erfasst. Es bleibt **portabel** (Markdown + YAML), ist **parser-freundlich**, und so gestaltet, dass Tools (Obsidian + Dataview, Embeddings/Vektorsuche via Qdrant, Agenten) es **maschinenlesbar** nutzen können.
**Anspruch an die Struktur:**
- **Stabil**: robuste IDs, deterministische Dateinamen, konsistente Feldnamen
- **Atomar**: ein Kerninhalt pro Datei (keine Sammelcontainer)
- **Erweiterbar**: neue Typen (z. B. `milestone`, `manifesto`) jederzeit möglich
- **Portabel**: reines Markdown + YAML → funktioniert in Obsidian, Git und Parsern
- **Vernetzbar**: systematische Links/Backlinks erzeugen ein sinnvoll navigierbares Netz
- **Parser-freundlich**: wiederkehrende Abschnittsüberschriften; Felder/Enums klar definiert
- **Atomar**: eine Kernaussage/ein zentrales Thema pro Datei (keine Sammelcontainer)
- **Erweiterbar**: neue Typen jederzeit möglich (ohne Migrationsschmerz)
- **Portabel**: pures Markdown + YAML → funktioniert in Obsidian, Git, Parsern
- **Vernetzbar**: systematische Links/Backlinks bilden ein navigierbares Wissensnetz
- **Parser-freundlich**: wiederkehrende Abschnittsüberschriften, klare Enums
**Späterer Nutzen / Einsatzzwecke:**
- **Schnelles Wiederfinden**: Dataview-Abfragen, Filter, Dashboards
- **Selbstreflexion & Entwicklung**: persönliche Werte, Wendepunkte, Kinderentwicklung, Lernpfade
- **Automatisierung**: Vektor-Index (Qdrant), Embeddings, LLM-Q&A, Agenten-Workflows
- **Langfristiges Gedächtnis**: eigene Lebens-/Projektchronik reproduzierbar pflegen
- **Aufgaben-/Projektsteuerung**: im selben System, vernetzt mit Kontextwissen
**Nutzen / Einsatzzwecke:**
- **Schnelles Wiederfinden**: Dataview-Abfragen, Filter, Dashboards
- **LLM-gestütztes Arbeiten**: Q&A mit Kontext-Zitaten aus Chunks (RAG)
- **Agenten**: Vorschläge für Verbindungen/Struktur; Auflösen von „unresolved links“
- **Projektnavigation**: Aufgabenbeziehungen, Abhängigkeiten
- **Langfristiges Gedächtnis**: Lebens-/Projektchronik (rückblickend und planend)
- **Automatisierung**: Vektor-Index (Qdrant), Embeddings, LLM-Q&A, Agenten-Workflows
---
## 2. YAML-Frontmatter-Schema
> **Pflichtfelder:** `title`, `id`, `type`, `status`, `created`, `tags`
> **Empfohlen:** `updated`, `area`, `project`, `priority`, `aliases` (u. a.)
> **Empfohlen:** `updated`, `area`, `project`, `priority`, `aliases`, `lang`, `people`, `depends_on`, `source` u. a.
### 2.1 Feldübersicht
| Feld | Typ | Bedeutung | Beispiel(e) |
|---------------------|-------------------------------|---------------------------------------------------------------------------|------------------------------------------------------------------------------|
| `title` | string | Menschlich lesbarer Titel | `"Vektorsuche in Qdrant"` |
| `id` | string (slug/identifier) | **Stabile** technische ID (nie umbenennen) | `"20250902-1710-thought-obsidian-struktur"`, `"concept-persoenliches-leitbild"` |
| `type` | enum | Notiz-Typ | `thought`, `experience`, `task`, `project`, `source`, `concept`, `person`, `meeting`, `journal`, `milestone` |
| `status` | enum | Lebenszyklus | `idea`, `draft`, `active`, `paused`, `blocked`, `done`, `archived` |
| `created` | date/datetime | Erstellzeitpunkt | `2025-09-02` oder `2025-09-02T17:10:00+02:00` |
| `updated` | date/datetime | Letzte inhaltliche Änderung | `2025-09-02T18:05:00+02:00` |
| `tags` | string[] | Schlagwörter gemäß Taxonomie | `["area/mindnet","topic/obsidian","type/thought"]` |
| `area` | enum/string | Lebens-/Arbeitsbereich | `mindnet`, `family`, `karate`, `travel`, `health`, `home-automation`, … |
| `role` | string | Rolle/Hut (Filter) | `"father"`, `"researcher"`, `"project-owner"` |
| `project` | string | Zugehöriges Projekt (ID oder sprechend) | `"project-mindnet"` |
| `priority` | int (1–5) | 1 = hoch, 5 = niedrig | `2` |
| `effort_min` | int | Aufwand in Minuten (für `task`) | `90` |
| `due` | date | Fälligkeit (Task/Projekt) | `2025-09-10` |
| `start` | date | geplanter Start (Task/Projekt) | `2025-09-05` |
| `people` | string[] (Wikilinks erlaubt) | Beteiligte Personen | `["Ich","[[person-kathie]]"]` |
| `location` | string | Ort/Platz | `"Home Office"`, `"München"` |
| `source_url` | url | Kanonische URL (für `source`) | `"https://qdrant.tech/docs/"` |
| `authors` | string[] | Autoren (für `source`) | `["Jane Doe"]` |
| `published` | date | Veröffentlichungsdatum (für `source`) | `2024-11-20` |
| `accessed` | date | Zugriffsdatum (für `source`) | `2025-09-02` |
| `aliases` | string[] | Alternative Namen/Titel | `["Manifest","Leitbild"]` |
| `related_ids` | string[] | ID-basierte Verknüpfungen | `["concept-persoenliches-leitbild"]` |
| `embedding_exclude` | boolean | Von Embeddings/Index ausschließen | `false` |
| Feld | Typ | Bedeutung |
|--------------------|-------------------------------|---------------------------------------------------------------------------|
| `title` | string | Menschlich lesbarer Titel |
| `id` | string (slug/identifier) | **Stabile** ID; referenzierbar über Wikilinks |
| `type` | enum | `concept`, `thought`, `experience`, `task`, `project`, `journal`, `person`, `meeting`, `milestone`, … |
| `status` | enum | `draft` \| `active` \| `done` \| `archived` |
| `created` | date | Erstellungsdatum (ISO) |
| `updated` | date | Letzte Änderung (ISO) |
| `area` | string | Themen-/Lebensbereich (z. B. „mindnet“, „gesundheit“, „familie“) |
| `project` | string | Projekt-/Arbeitskontext |
| `tags` | list<string> | Taxonomische Tags (präfixiert, s. Abschnitt 4) |
| `aliases` | list<string> | Alternative IDs/Titel (Slug-Resolver) |
| `lang` | string | Sprache, optional (z. B. `de`, `en`) |
| `priority` | enum/int | Priorität, optional (`low`/`med`/`high` oder 1–5) |
| `due`, `effort_min`| date/int | Für Aufgaben/Projekte (Fälligkeit, Aufwand in Minuten) |
| `people` | list<string> | Beteiligte Personen/IDs |
| `depends_on` | list<string> | Abhängigkeiten auf andere IDs |
| `source` | string | Quelle (Artikel, Buch, Video, …) |
| `slug` | string | Stabiler Pfad-/Dateiname, falls abweichend |
### 2.2 Konventionen
- **IDs:** entweder Zeitstempel-basiert (`YYYYMMDD-HHMM-type-slug`) **oder** stabile, sprechende (`concept-*`, `project-*`, `person-*`).
- **Datums-/Zeitformat:** ISO 8601, Zeiten möglichst mit TZ (z. B. `+02:00`).
- **Felder:** klein geschrieben; zusammengesetzte Felder in `snake_case`.
- `id` ist **menschenlesbar** (Slug), eindeutig im Vault; `aliases` dienen als Fallback-IDs.
- Datumsformat: ISO `YYYY-MM-DD`.
- Keine duplizierten Tags; Präfixe nutzen (`area/…`, `type/…`, `topic/…`).
- Frontmatter nur Fakten/Metadaten, **keine** ausufernden Inhalte (die stehen in den Body-Abschnitten).
### 2.3 Minimalbeispiel Frontmatter
---
title: "Kurzer, klarer Gedanke"
id: "20250902-1715-thought-klarer-gedanke"
type: "thought"
status: "idea"
created: 2025-09-02T17:15:00+02:00
updated: 2025-09-02T17:15:00+02:00
tags: ["area/mindnet","type/thought","topic/obsidian"]
---
## 2.4 Enum-Werte
title: "Gedanke: YAML-Standards"
id: thought-yaml-standards
type: thought
status: draft
created: 2025-09-02
updated: 2025-09-09
area: mindnet
project: project-mindnet
tags: [area/mindnet, type/thought, topic/yaml]
aliases: [yaml-gedanken]
lang: de
Zur Sicherstellung der Konsistenz werden für bestimmte Felder feste Wertemengen (Enums) verwendet:
- **type**
- `idea` – spontane Gedanken, Inspirationen
- `experience` – persönliche Erfahrungen, Reflexionen
- `task` – konkrete Aufgaben
- `project` – Projekte, bestehend aus mehreren Tasks
- `concept` – abstrakte Konzepte, Modelle, Methoden
- `milestone` – wichtige Ereignisse oder Wendepunkte
- `person` – Personen (z. B. Kontakte, Vorbilder)
- `meeting` – Besprechungen, Treffen, Gespräche
- `resource` – externe Quellen (Artikel, Bücher, Links)
- `journal` – Tagebuchnotizen
- **status**
- `open`
- `in-progress`
- `done`
- `blocked`
- `canceled`
- **priority**
- `low`
- `medium`
- `high`
- **area** (Beispiele – erweiterbar)
- `personal`
- `work`
- `family`
- `karate`
- `health`
- `finance`
### 2.4 Enum-Werte (Beispiele)
- `type`: `concept`, `thought`, `experience`, `task`, `project`, `journal`, `person`, `meeting`, `milestone`, `manifesto`
- `status`: `draft`, `active`, `done`, `archived`
- `priority`: `low`, `med`, `high` oder 1–5
---
## 3. Dateinamen-Konventionen
> Keine Sonderzeichen wie `: / \` im Dateinamen.
- **Zeitbasierte Notizen (Gedanken, Journal, tagesgebundene Einträge):**
`YYYYMMDD-HHMM-<type>-<slug>.md`
Beispiel: `20250902-1710-thought-obsidian-struktur.md`
- **Zeitunabhängige Wissensknoten (Konzepte, Personen, Projekte, Leitbild):**
`<type>-<slug>.md`
Beispiele: `concept-vektorsuche-qdrant.md`, `project-mindnet.md`, `person-kathie.md`, `concept-persoenliches-leitbild.md`
- **Ordnerstruktur (Empfehlung):**
00_inbox/
10_thoughts/
20_experiences/
30_projects/
31_tasks/
40_concepts/
50_sources/
60_people/
70_meetings/
80_journal/
90_templates/
_attachments/
_meta/
- `YYYY-MM-DD_title.md` oder `slug.md`.
- Pfade **relativ** zum Vault; keine absoluten Pfade (einheitliche Slashes `/`).
- Verzeichnisse nach eigener Ordnung, empfohlen: `10_thoughts/`, `20_concepts/`, `30_projects/`, `40_journal/`, …
---
## 4. Tagging-Regeln & Taxonomie
- **Hierarchische Tags:**
- `area/*` – Lebens-/Arbeitsbereiche: `area/mindnet`, `area/family`, `area/karate`, `area/health`, …
- `type/*` – optionaler Spiegel von `type`: `type/thought`, `type/experience`, …
- `topic/*` – thematische Schwerpunkte: `topic/obsidian`, `topic/yaml`, `topic/qdrant`, `topic/werte`, …
- optional: `place/*`, `person/*`, `level/*` (z. B. `person/rouven`, `person/rohan`)
- **Regeln:**
- Jede Notiz hat **mindestens ein** `area/*`.
- `topic/*` sparsam, aber konsistent; ein Mapping in `_meta/tags.md` pflegen.
- Möglichst **keine** losen Ein-Wort-Tags ohne Präfix (verhindert Wildwuchs).
- Präfixe verwenden: `area/…`, `type/…`, `topic/…`, `status/…`.
- Möglichst **keine** losen Ein-Wort-Tags ohne Präfix (verhindert Wildwuchs).
- Für Dataview konsistente Namespaces beibehalten (z. B. `topic/llm`, `topic/lernen`).
---
## 5. Backlink- & Link-Regeln
- **Wikilinks** verwenden: `[[stabile-id-oder-dateiname]]`
- Im **Fließtext** bei erster Nennung verlinken; am **Ende** die Sektion **„Mögliche Verbindungen“** pflegen:
- **Wikilinks**: `[[stabile-id]]` oder `[[Titel|stabile-id]]`
- Im **Fließtext** verlinken (Forwardlinks); am **Ende** optional **„Mögliche Verbindungen“** redaktionell pflegen:
## Mögliche Verbindungen
- [[concept-persoenliches-leitbild]]
- [[project-mindnet]]
- **Linkrichtung:** „aufwärts“ (Detail → Konzept/Leitbild) und „seitwärts“ (verwandte Knoten).
- Optional zusätzlich **ID-Relationen** im YAML (`related_ids`) für Parser.
- **Linkrichtung:** „aufwärts“ (Detail → Konzept/Leitbild) und „seitwärts“ (verwandte Knoten).
- Optional zusätzliche **ID-Relationen** im YAML (`related_ids`) für Parser.
- **Unresolved Links:** Links auf noch nicht existierende Ziele sind zulässig; der Importer schreibt `status: unresolved`-Edges (später durch Resolver/Agent heilbar).
## 5.1 Edge-Typen
---
Beziehungen zwischen Notizen, Chunks und Objekten werden als **Edges** gespeichert. Jeder Edge erhält einen `type` und optionale `meta`-Informationen (z. B. Gewichtung, Richtung).
## 5.1 Edge-Typen & Semantik (Graph)
- **belongs_to**
Chunk → Note (ein Chunk gehört zu genau einer Note)
Beziehungen werden als **Edges** mit neuem Payload-Schema gespeichert:
- **references**
Note → Note (eine Notiz verweist auf eine andere)
kind : "belongs_to" | "next" | "prev" | "references" | "backlink" | "unresolved"
source_id : ID des Quellknotens (Chunk- oder Note-ID)
target_id : ID des Zielknotens (Note- oder Chunk-ID)
scope : "chunk" | "note"
note_id : Owner-Note des Edges (für schnelles Filtern/Purge)
status : optional, z. B. "unresolved"
- **backlink**
Automatisch generiert: Gegenkante von `references`
**Kantenarten**
- **belongs_to** — *Chunk → Note*
Jeder Chunk gehört zu **genau einer** Note. *Scope:* `chunk`.
- **depends_on**
Task → Task oder Task → Project (Aufgabe hängt von anderer ab)
- **prev / next** — *Chunk → Chunk*
Lineare Reihenfolge innerhalb derselben Note; **symmetrisch** angelegt (d. h. `prev` und `next` konsistent). *Scope:* `chunk`.
- **assigned_to**
Task → Person (eine Aufgabe ist einer Person zugeordnet)
- **references** — *Chunk → Note*
Aus `[[Wikilinks]]` oder Markdown-Links im **Chunk-Text** (präzise Herkunft). *Scope:* `chunk`.
- **discussed_in**
Note/Concept → Meeting (ein Thema wurde in einem Meeting behandelt)
- **backlink** — *Note → Note*
Automatisch generierte Gegenkante zu `references` (pro Note **dedupliziert**). *Scope:* `note`.
- **authored_by**
Note → Person (z. B. externer Autor oder eigene Urheberschaft)
- **unresolved**
Edge mit `status: "unresolved"`, wenn `target_id` (noch) nicht existiert. Wird später vom Resolver/Agent ersetzt.
- **related**
Generische Relation für schwache Assoziationen
- **Optional:** `references:note` — *Note → Note*
Zusätzliche Forwardlinks auf Note-Ebene; standardmäßig **deaktiviert**, um Doppelzählungen mit `references` (Chunk-Scope) zu vermeiden. Aktivierung per ENV/Flag möglich.
**Performanzhinweise (Qdrant)**
- Edges werden dedupliziert über `(kind, source_id, target_id, scope)`.
- `note_id` ist Pflichtfeld im Edge-Payload (Owner-Note).
- Payload-Indizes für Qdrant anlegen:
edges : kind (KEYWORD), scope (KEYWORD), source_id (KEYWORD), target_id (KEYWORD), note_id (KEYWORD)
chunks : note_id (KEYWORD), chunk_index (INTEGER)
notes : note_id (KEYWORD)
---
## 6. Abschnitts-Konventionen im Body
Einheitliche Überschriften erleichtern spätere Parser und Abfragen.
Einheitliche Überschriften erleichtern Parser, Chunking und Abfragen. Typ-spezifische Empfehlungen:
- **Gedanke (`thought`)**
`## Zusammenfassung` · `## Begründung / Details` · `## Belege / Quellen` · `## Nächste Schritte` · `## Mögliche Verbindungen`
- **Erfahrung (`experience`)**
`## Kontext` · `## Beobachtung` · `## Interpretation` · `## Implikationen` · `## Mögliche Verbindungen`
- **Aufgabe (`task`)**
`## Checkliste` · `## Notizen` · `## Mögliche Verbindungen`
`## Checkliste` · `## Notizen` · `## Nächste Schritte` · `## Mögliche Verbindungen`
- **Projekt (`project`)**
`## Scope` · `## Arbeitspakete` · `## Risiken & Gegenmaßnahmen` · `## Status / Fortschritt` · `## Mögliche Verbindungen`
- **Journal (`journal`)**
`## Tageszusammenfassung` · `## Highlights` · `## Gelernt / Notizen` · `## Mögliche Verbindungen`
`## Tageszusammenfassung` · `## Highlights` · `## Learnings` · `## Mögliche Verbindungen`
- **Meeting (`meeting`)**
`## Agenda` · `## Notizen` · `## Entscheidungen` · `## Aufgaben` · `## Mögliche Verbindungen`
---
## 7. Abbildung persönlicher Inhalte auf Typen
- **Persönliches Leitbild** → `type: "concept"` (oder optional neuer Typ `manifesto`)
Datei: `concept-persoenliches-leitbild.md` (zeitunabhängig)
Verlinkt zu prägenden Erfahrungen und Wendepunkten.
- **Erfahrungen, die dich geprägt haben** → `type: "experience"`
Je **eine** prägende Erfahrung pro Datei; klarer Kontext + Interpretation.
- **Wendepunkte im Leben** → `type: "milestone"`
Je Wendepunkt ein Knoten; verlinkt zu den auslösenden Erfahrungen.
- **Aktuelle Erfahrungen** → `type: "experience"`, `status: "active"`
Bei Bedarf später in „prägende“ Erfahrungen überführen.
- **Entwicklungsschritte der Kinder** → `type: "journal"` (chronologisch) **oder** `experience` (wenn es prägend ist); Tags `person/<name>`.
- **Tagebucheinträge** → `type: "journal"`; ein Eintrag pro Tag; tagesbasierte Dateinamen.
Damit entsteht ein **netzartiges Persönlichkeitsprofil** mit klaren Pfaden zwischen Werten (Leitbild), Ereignissen (Erfahrungen), Wendepunkten und fortlaufenden Beobachtungen (Journal).
**Richtlinien:**
- Wähle den Typ nach **Hauptintention** (Definition, Gedanke, Beobachtung, Aufgabe, Projekt, …).
- **Konzepte** (`concept`): langlebige Definitionen, Prinzipien, Leitbilder.
- **Gedanken** (`thought`): explorative Ideen, noch nicht stabil (können später bei Reife in `concept` überführt werden).
- **Erfahrungen** (`experience`): Beobachtungen & Learnings aus der Praxis.
- **Aufgaben** (`task`): konkrete, umsetzbare To-dos mit `due`/`effort_min`.
- **Projekte** (`project`): Ziele, Deliverables, Arbeitspakete, Abhängigkeiten.
- **Journal** (`journal`): tagesbasierte Notizen, Reflexionen, Reiseberichte.
- **Personen** (`person`): Kontakte, Profile, Bezüge, Gespräche.
- **Meetings** (`meeting`): Agenda, Notizen, Entscheidungen, Folgeaufgaben.
- **Meilensteine** (`milestone`): wichtige Wendepunkte im Lebens-/Projektverlauf.
---
## 8. Beispiel-Notizen
### 8.1 Gedanke (`thought`)
---
title: "Gedanke: Einheitliche YAML-Standards steigern Recall"
id: "20250902-1830-thought-yaml-recall"
type: "thought"
status: "idea"
created: 2025-09-02T18:30:00+02:00
updated: 2025-09-02T18:30:00+02:00
tags: ["area/mindnet","type/thought","topic/yaml","topic/recall"]
area: "mindnet"
project: "project-mindnet"
aliases: []
---
### 8.1 Gedanke (`thought`) – Beispiel
**Frontmatter**
title: "Gedanke: Übungen für tiefe Arbeit"
id: thought-deep-work-uebungen
type: thought
status: active
created: 2025-08-21
updated: 2025-09-05
area: lernen
project: project-self-improvement
tags: [area/lernen, type/thought, topic/fokus]
aliases: [deep-work-ideen]
lang: de
**Body (Ausschnitt)**
## Zusammenfassung
Konsistente YAML-Felder verbessern Filter, Dataview-Queries und Vektor-Retrieval.
Kurze tägliche Routinen (z. B. Timer-Blöcke, Ablenkungslog) erhöhen meinen Fokus.
## Begründung / Details
- Parser benötigen stabile Feldnamen (z. B. `type`, `status`).
- Einheitliche Werte erleichtern Dashboards und Automationen.
- 25–45 Min Timerblöcke mit 5 Min Pause
- Ablenkungen sofort notieren
- Abschluss-Log am Ende des Tages
## Mögliche Verbindungen
- [[concept-deep-work]]
- [[project-productivity-week]]
### 8.2 Konzept (`concept`) – Beispiel
**Frontmatter**
title: "Konzept: Deep Work"
id: concept-deep-work
type: concept
status: active
created: 2024-05-14
updated: 2025-08-01
area: lernen
tags: [area/lernen, type/concept, topic/fokus]
aliases: [konzept-tiefe-arbeit]
lang: de
**Body (Ausschnitt)**
## Definition
Tiefe Arbeit = kognitiv anspruchsvolle Arbeit ohne Ablenkung.
## Belege / Quellen
- [[source-obsidian-properties]]
- [[concept-vektorsuche-qdrant]]
## Nächste Schritte
- [ ] `tags`-Mapping in `_meta/tags.md` erstellen
- [ ] Beispiel-Queries für Dataview hinterlegen
- Buch: Cal Newport – Deep Work
## Mögliche Verbindungen
- [[project-mindnet]]
- [[20250902-1730-task-yaml-standard-migration]]
- [[thought-deep-work-uebungen]]
### 8.2 Erfahrung (`experience`)
---
title: "Erfahrung: Journal → Erfahrung extrahieren erhöht Klarheit"
id: "20250902-1840-experience-journal-extraktion"
type: "experience"
status: "active"
created: 2025-09-02T18:40:00+02:00
updated: 2025-09-02T18:40:00+02:00
tags: ["area/personal","type/experience","topic/journal","topic/reflexion"]
area: "personal"
project: "project-mindnet"
---
### 8.3 Aufgabe (`task`) – Beispiel
## Kontext
Wiederkehrende Journaleinträge enthalten Rohmaterial für prägende Einsichten.
**Frontmatter**
## Beobachtung
Wird Material regelmäßig zu `experience`-Knoten verdichtet, sind spätere Bezüge einfacher.
title: "Task: Wochenplanung erstellen"
id: task-week-planning
type: task
status: active
created: 2025-09-07
updated: 2025-09-07
due: 2025-09-11
effort_min: 45
area: organisation
project: project-productivity-week
tags: [area/organisation, type/task, topic/planung]
lang: de
## Interpretation
Abstraktion + Verlinkung (z. B. auf [[concept-persoenliches-leitbild]]) erhöhen Nutzen und Wiederfindbarkeit.
## Implikationen
Pro Woche 15–30 Minuten „Verdichtungs-Review“ einplanen.
## Mögliche Verbindungen
- [[journal-20250902]]
- [[concept-persoenliches-leitbild]]
### 8.3 Aufgabe (`task`)
---
title: "Task: YAML-Standard in Altbeständen ergänzen"
id: "20250902-1850-task-yaml-migration"
type: "task"
status: "active"
created: 2025-09-02
updated: 2025-09-02
due: 2025-09-10
start: 2025-09-03
priority: 2
effort_min: 120
area: "mindnet"
project: "project-mindnet"
tags: ["area/mindnet","type/task","topic/migration"]
depends_on: []
---
**Body (Ausschnitt)**
## Checkliste
- [ ] Triage: Notiz-Typ bestimmen
- [ ] Minimal-YAML ergänzen (Pflichtfelder)
- [ ] Dateinamen vereinheitlichen
- [ ] „Mögliche Verbindungen“ pflegen
## Notizen
Beginne mit zuletzt genutzten Notizen (Pareto 20/80).
- Ziele der Woche definieren
- 5 Fokusblöcke eintragen
- 2 Lerneinheiten terminieren
## Mögliche Verbindungen
- [[project-mindnet]]
- [[20250902-1830-thought-yaml-recall]]
- [[project-productivity-week]]
- [[thought-deep-work-uebungen]]
---
## 9. Schrittweise Migration bestehender freier Notizen
**Phase A – Triage (schnell)**
1. Sichtung & **Typ** bestimmen (`type`).
2. **Minimal-YAML** einfügen (`title`, `id`, `type`, `status=draft`, `created≈Dateidatum`, `tags`).
3. **Dateiname** grob anpassen (Schema + Slug).
**Phase B – Strukturieren (fokussiert)**
1. **Abschnitte** nach Typ-Template ergänzen.
2. **Zerlegen**: mehrere Gedanken/Ereignisse → je **eigene Datei**, ursprüngliche Datei wird zum **Index** mit Links.
3. **Verlinken**: relevante `[[Knoten]]` + **„Mögliche Verbindungen“** pflegen.
**Phase C – Verfeinern (bei Bedarf)**
1. **Status & Felder** pflegen (`status`, `priority`, `due`, `effort_min`).
2. **Tag-Harmonisierung**: Mapping-Tabelle pflegen (`_meta/tags.md`).
3. **Aliases** ergänzen (Such-/Linkvarianten).
**Priorisierung:** Starte mit **aktuellen & häufig genutzten** Notizen (Pareto-Prinzip), Altbestände nachziehen, wenn sie wieder gebraucht werden.
1. **Frontmatter ergänzen** (min. `id`, `title`, `type`, `status`, `created`, `tags`).
2. **Abschnittsstruktur** an Typ anpassen (Konventionen s. Abschnitt 6).
3. **Wikilinks** im Body setzen (statt bloßer Erwähnungen).
4. **Tags normalisieren** (Präfixe, Kleinschreibung, keine Dubletten).
5. **Aliases** angeben, falls Notiz zuvor unter anderem Namen existierte.
6. **Testlauf**: Import (Dry-Run), danach Apply, Audit/Validate prüfen.
---
## 10. Dataview-Beispiele (direkt nutzbar)
**Offene Aufgaben dieser Woche (nach Priorität):**
TABLE due, priority, effort_min
FROM "31_tasks"
WHERE type = "task" AND status != "done"
AND due >= date(today) - dur(1 week)
AND due <= date(today) + dur(1 week)
SORT priority ASC, due ASC
**Aktive Gedanken der letzten 30 Tage**
**Aktive Projekte mit Meilensteinen:**
LIST
FROM "30_projects"
WHERE type = "project" AND status = "active"
SORT priority ASC, file.ctime DESC
**Gedanken im Bereich mindnet, jüngste zuerst:**
TABLE created, status
TABLE title, created, updated, area
FROM "10_thoughts"
WHERE type = "thought" AND area = "mindnet"
SORT created DESC
LIMIT 50
WHERE type = "thought" AND status = "active" AND created >= date(today) - dur(30 days)
SORT updated DESC
**Quellen ohne `source_url` (Pflegebedarf):**
TABLE title, created
FROM "50_sources"
WHERE type = "source" AND (source_url = "" OR !source_url)
**Offene Tasks mit Fälligkeit**
TABLE title, due, effort_min, project, area
FROM "30_tasks"
WHERE type = "task" AND status = "active" AND due
SORT due ASC
**Konzepte je Topic**
TABLE title, area, tags
FROM "20_concepts"
WHERE contains(tags, "type/concept")
GROUP BY choice(regexreplace(join(filter(tags, (t) => startswith(t, "topic/")), ", "), "^topic/", ""))
**Verknüpfungskandidaten (redaktionell, nicht automatisch)**
*(Liste am Ende der jeweiligen Notiz in „Mögliche Verbindungen“)*
---
## 11. Validierung & Pflege
- **Wöchentlicher Review-Slot (15–30 Min.):**
- Neue Notizen triagieren (`type`, `status`, `area`)
- 5 Alt-Notizen migrieren (YAML + Dateiname + Verlinkung)
- **Dataview-Checks:** fehlende `source_url`, offene Tasks, aktive Projekte, veraltete `status`.
- **Optional (technisch):**
- **Pre-commit Hook**: prüft Pflichtfelder (`title`, `id`, `type`, `status`, `created`, `tags`)
- **ID-Generator**: `YYYYMMDD-HHMM-type-slug` bei Neuanlage
- **Link-Linter**: prüft tote `[[Links]]`
- **Linter/Validator** prüfen Pflichtfelder und Wertebereiche (Enums, ISO-Datum).
- **Resolver** löst `unresolved`-Edges, wenn neue Notizen/Aliases entstehen.
- **Idempotente Re-Imports**: Hash-Steuerung konfigurierbar:
- `MINDNET_HASH_MODE`: `body` \| `frontmatter` \| `body+frontmatter` (Default: `body`)
- `MINDNET_HASH_NORMALIZE`: `canonical` \| `none` (Default: `canonical`)
- **Edge-Invarianten** (Audit):
- `belongs_to == #Chunks`
- `next == prev == Σ(max(chunks_in_note−1, 0))`
- `references (chunk) == Σ(Chunk-Wikilinks)`
- `backlink == Σ(eindeutige Wikilinks je Note)`
- **Roundtrip-Test**: Import → Export → Diff muss Body verlustfrei rekonstruieren.
---
## 12. Versions- & Änderungsrichtlinien
## 12. Qdrant-Ablage & Indizes
- Dieses Dokument pflegt `version` & `updated`.
- **Breaking Changes** (z. B. Feldumbenennungen) in `_meta/changelog.md` dokumentieren.
- **Migrationen** (Tag-Refactorings, Typänderungen) als Skript oder Batch-Checkliste planen.
**Collections**
- `{prefix}_notes` – Vektor optional (Nullvektor oder Zentroid), Payload inkl. Frontmatter & `fulltext`
- `{prefix}_chunks` – 384d Embedding je Chunk, Payload inkl. `text`, `chunk_index`, `note_id`
- `{prefix}_edges` – 1d Dummy-Vektor, Payload im neuen Schema (s. 5.1)
**IDs & Idempotenz**
- Deterministisch/UUIDv5 über stabile Schlüssel (`note_id`, `chunk_id = note_id#cNN`, `edge_id` aus `(kind, source_id, target_id, scope)`)
- Re-Imports erzeugen keine Duplikate (Upsert)
**Payload-Indizes (Performance)**
notes : note_id (KEYWORD)
chunks : note_id (KEYWORD), chunk_index (INTEGER)
edges : kind (KEYWORD), scope (KEYWORD), source_id (KEYWORD), target_id (KEYWORD), note_id (KEYWORD)
**Delete/Purge**
- Selektives Löschen in Edges/Chunks per `note_id`-Filter (schnell, sicher).
- `--sync-deletes` (geplant): Qdrant→Vault Diffs gezielt entfernen (mit Dry-Run).
---
## 13. Typen-Kurzreferenz
## 13. LLM/RAG & Agenten – Arbeitsweise (Überblick)
- `thought` – Gedanke/These
- `experience` – Beobachtung/Erfahrung mit Interpretation & Implikationen
- `task` – umsetzbare Arbeitseinheit (mit `due`, `effort_min`, `priority`)
- `project` – Container für Ziele/Tasks/Meilensteine
- `source` – externe Quelle (Artikel, Buch, Video)
- `concept` – definierter Begriff / Prinzip / Leitbild
- `person` – Bezugsperson/Kontakt
- `meeting` – Termin mit Agenda, Notizen, erzeugten Aufgaben
- `journal` – Tagebuch-/Reiseeintrag (tagesbasiert)
- `milestone` – Wendepunkt / Meilenstein im Lebens-/Projektverlauf
**Retriever (Hybrid)**
1) **kNN (Chunks)** in Qdrant → Top-k Kandidaten (Semantik).
2) **Nachbarschafts-Expand** (1 Hop) über Edges (`belongs_to`, `references`, `backlink`) → zusätzliche Kontexte.
3) **Rerank** (optional BM25/LLM-score).
4) **Prompt** mit Zitaten/Belegen (Verweis auf `path` + Abschnittstitel).
**Agentisches Einordnen (neue Inputs)**
- **Chunking + Embedding** → **kNN-Kandidaten**
- Klassifikation (`type`, `area`, `project`) via Heuristik/LLM
- Edge-Vorschläge: `references` (Semantik + geteilte Tags/Area), `belongs_to` (beste Einordnung)
- Falls kein Ziel existiert → `unresolved` erzeugen oder **Stub-Note** anlegen
- **Human-in-the-loop**: Vorschläge bestätigen, dann Commit via Importer
**Graph-Layer (optional, empfohlen)**
- Zusätzliche SQLite/Postgres-Tabellen `nodes/edges/aliases` für 2–3-Hop-Queries, Pfadsuche, Zählungen.
- Importer pflegt Qdrant **und** SQL (UPSERT).
- Graph-Features (Degree, Communities, optional PageRank) regelmäßig berechnen und als Felder in `notes.payload` speichern.
---
## 14 Erweiterungen
## 14. Versions- & Änderungsrichtlinien
Zukünftige Typen möglich (z. B. decision, recommendation).
- **Kleine Änderungen** direkt in der bestehenden Notiz (Frontmatter `updated` anpassen).
- **Große Strukturänderungen** (z. B. neuer Typ) als neue Notiz mit Verweis; alte Note verlinken/archivieren (`status: archived`).
- **IDs nie recyceln** (Konstanz für Referenzen und Edges).
- **Aliases** nutzen, wenn sich Titel/Slug ändert (Resolver kann beides auflösen).
- **Commit-Meldungen** im Git prägnant strukturieren:
- `feat(note): …` · `fix(frontmatter): …` · `chore(tags): …` · `refactor(structure): …`
Personalisierung durch zusätzliche Properties (values, goals)
---
## 15. Typen-Kurzreferenz
- **concept** — Definitionen, Leitbilder, Prinzipien
Empfohlene Abschnitte: *Definition*, *Beispiele*, *Belege*, *Mögliche Verbindungen*
- **thought** — Ideen, Entwürfe, Skizzen
Abschnitte: *Zusammenfassung*, *Details*, *Nächste Schritte*, *Mögliche Verbindungen*
- **experience** — Beobachtungen, Learnings
Abschnitte: *Kontext*, *Beobachtung*, *Interpretation*, *Implikationen*, *Mögliche Verbindungen*
- **task** — konkrete To-dos
Felder: `due`, `effort_min`; Abschnitte: *Checkliste*, *Notizen*, *Mögliche Verbindungen*
- **project** — Ziele, Deliverables, Arbeitspakete
Abschnitte: *Scope*, *Arbeitspakete*, *Risiken*, *Status*, *Mögliche Verbindungen*
- **journal** — tagesbasierte Einträge
Abschnitte: *Tageszusammenfassung*, *Highlights*, *Learnings*, *Mögliche Verbindungen*
- **person** — Kontakte, Profile
Felder: `people` (Selbst-/Fremd-ID), *Notizen*, *Mögliche Verbindungen*
- **meeting** — Termine, Protokolle
Abschnitte: *Agenda*, *Notizen*, *Entscheidungen*, *Aufgaben*, *Mögliche Verbindungen*
- **milestone** — Wendepunkte
Abschnitte: *Kontext*, *Bedeutung*, *Verknüpfungen*
---
## 16. Erweiterungen
- Neue Typen (z. B. `decision`, `recommendation`, `resource`) können ohne Bruch ergänzt werden.
- Personalisierung durch zusätzliche Properties (`values`, `goals`) in Frontmatter.
- Internationale Inhalte: `lang` pflegen, optional **mehrsprachige** Embeddings (z. B. mE5).
---
## 17. Anhang – Beispiele & Snippets
**Beispiel: YAML-Frontmatter für Projekt**
title: "Projekt: Produktivität Woche 37"
id: project-productivity-week
type: project
status: active
created: 2025-09-08
updated: 2025-09-09
area: organisation
tags: [area/organisation, type/project, topic/planung]
people: [ich]
depends_on: [concept-deep-work]
lang: de
**Beispiel: Redaktions-Sektion (keine Kanten-Erzeugung)**
## Mögliche Verbindungen
- [[concept-wochenplanung]]
- [[thought-deep-work-uebungen]]
- [[journal-2025-09-08]]
**CLI: Import & Audit**
# Dry-Run Import
python3 -m scripts.import_markdown --vault ./vault
# Apply mit strenger Hash-Erkennung (jede Änderung zählt)
python3 -m scripts.import_markdown --vault ./vault --apply --hash-normalize none
# Audit Edges vs. Erwartungen
python3 -m scripts.audit_edges_vs_expectations --vault ./vault
---
## 18. Glossar
- **Alias**: alternativer Name/Slug, der auf dieselbe Note verweist
- **Backlink**: automatisch erzeugte Gegenkante zu `references` (Note-Scope)
- **Chunk**: semantisch sinnvoller Textabschnitt einer Note, inkl. Embedding
- **Owner-Note**: Note, zu der ein Edge gehört (`note_id` im Edge-Payload)
- **Resolver**: Prozess/Script, das `unresolved`-Edges bei späterer Ziel-Existenz heilt
---
## 19. Verweise
- `chunking_strategy.md` – Details zu Chunkgrößen, Overlaps, Abschnittsregeln
- `schemas/note.schema.json` – Validierung von Frontmatter‐Feldern
- Import/Export-Skripte: `scripts/import_markdown.py`, `scripts/export_markdown.py`
- Qdrant-Client/Setup: `app/core/qdrant.py`, `app/core/qdrant_points.py`
---
## 20. Änderungsverlauf
- **1.3.0 (2025-09-09)**
- Edge-Politik präzisiert: `references` (Chunk-Scope), `backlink` (Note-Scope), `references:note` optional.
- `note_id` als Pflichtfeld im Edge-Payload (Owner).
- Qdrant-Payload-Indizes ergänzt (Performanz).
- Beispiele & Dataview-Snippets erweitert.
- **1.2.0 (2025-09-02)**
- Erstfassung des Knowledge-Designs.
+94 -81
View File
@@ -1,44 +1,39 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Script: import_markdown.py — Markdown → Qdrant (Notes, Chunks, Edges)
Version: 3.2.0
Script: scripts/import_markdown.py — Markdown → Qdrant (Notes, Chunks, Edges)
Version: 3.4.1
Datum: 2025-09-09
Kurzbeschreibung
----------------
Liest Markdown-Dateien aus einem Vault ein und schreibt Notes, Chunks und Edges
idempotent nach Qdrant. Change-Detection basiert standardmäßig auf dem **Body-Hash**.
Neu: Hash-Modus und Normalisierung sind auch per **CLI** steuerbar.
- Liest Markdown-Dateien ein, erzeugt Notes/Chunks/Edges **idempotent**.
- Change-Detection (nur **Inhalte**, keine FS-Zeitstempel) konfigurierbar:
* ``--hash-mode``: body | frontmatter | body+frontmatter | full (Alias)
- Env: ``MINDNET_HASH_MODE`` **oder** ``MINDNET_HASH_COMPARE`` (Body/Frontmatter/Full)
* ``--hash-normalize``: canonical | none (Default: canonical)
* ``--hash-source``: parsed (Default) | raw
- "raw" hasht den **ungeparsten** Body aus der Datei (Frontmatter vorher entfernt).
- Optionales Diff-Logging: ``--debug-hash-diff`` zeigt bei Bedarf einen kompakten Diff.
ENV / Qdrant
------------
- QDRANT_URL (oder QDRANT_HOST/QDRANT_PORT)
- QDRANT_API_KEY (optional)
- QDRANT_URL | QDRANT_HOST/QDRANT_PORT | QDRANT_API_KEY
- COLLECTION_PREFIX (Default: mindnet)
- VECTOR_DIM (Default: 384)
- MINDNET_HASH_MODE: "body" (Default) | "frontmatter" | "body+frontmatter"
- MINDNET_HASH_NORMALIZE: "canonical" (Default) | "none"
CLI (übersteuert ENV)
---------------------
--hash-mode body|frontmatter|body+frontmatter
--hash-normalize canonical|none
- MINDNET_NOTE_SCOPE_REFS: true|false (Default: false)
Aufruf
------
python3 -m scripts.import_markdown --vault ./vault
python3 -m scripts.import_markdown --vault ./vault --apply
python3 -m scripts.import_markdown --vault ./vault --apply --purge-before-upsert
python3 -m scripts.import_markdown --vault ./vault --note-id 20250821-foo --apply
python3 -m scripts.import_markdown --vault ./vault --apply --embed-note
# Feingranulare Erkennung (jede Kleinigkeit im Body zählt):
python3 -m scripts.import_markdown --vault ./vault --hash-normalize none
python3 -m scripts.import_markdown --vault ./vault --apply --hash-source raw --hash-normalize none
MINDNET_HASH_COMPARE=Full python3 -m scripts.import_markdown --vault ./vault --apply
"""
from __future__ import annotations
import argparse
import difflib
import json
import os
import sys
@@ -51,12 +46,17 @@ from app.core.parser import (
read_markdown,
normalize_frontmatter,
validate_required_frontmatter,
extract_wikilinks,
)
from app.core.note_payload import make_note_payload
from app.core.chunker import assemble_chunks
from app.core.chunk_payload import make_chunk_payloads
from app.core.qdrant import QdrantConfig, get_client, ensure_collections
from app.core.edges import build_edges_for_note
from app.core.qdrant import (
QdrantConfig,
get_client,
ensure_collections,
ensure_payload_indexes,
)
from app.core.qdrant_points import (
points_for_chunks,
points_for_note,
@@ -65,15 +65,14 @@ from app.core.qdrant_points import (
)
try:
from app.core.embed import embed_texts, embed_one # optional
from app.core.embed import embed_texts # optional
except Exception:
embed_texts = None
embed_one = None
# -----------------------------------------------------------------------------
# Hilfsfunktionen
# -----------------------------------------------------------------------------
# ---------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------
def iter_md(root: str) -> List[str]:
out: List[str] = []
@@ -91,12 +90,9 @@ def iter_md(root: str) -> List[str]:
def collections(prefix: str) -> Tuple[str, str, str]:
return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges"
def fetch_existing_note_hash(client, prefix: str, note_id: str) -> Optional[str]:
def fetch_existing_note_payload(client, prefix: str, note_id: str) -> Optional[Dict]:
notes_col, _, _ = collections(prefix)
f = rest.Filter(must=[rest.FieldCondition(
key="note_id",
match=rest.MatchValue(value=note_id),
)])
f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
points, _ = client.scroll(
collection_name=notes_col,
scroll_filter=f,
@@ -106,20 +102,13 @@ def fetch_existing_note_hash(client, prefix: str, note_id: str) -> Optional[str]
)
if not points:
return None
pl = points[0].payload or {}
return pl.get("hash_fulltext")
return points[0].payload or {}
def purge_note_artifacts(client, prefix: str, note_id: str) -> None:
_, chunks_col, edges_col = collections(prefix)
f_chunks = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
client.delete(collection_name=chunks_col, points_selector=f_chunks, wait=True)
should = [
rest.FieldCondition(key="source_id", match=rest.MatchText(text=f"{note_id}#")),
rest.FieldCondition(key="target_id", match=rest.MatchText(text=f"{note_id}#")),
rest.FieldCondition(key="source_id", match=rest.MatchValue(value=note_id)),
rest.FieldCondition(key="target_id", match=rest.MatchValue(value=note_id)),
]
f_edges = rest.Filter(should=should)
f_edges = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
client.delete(collection_name=edges_col, points_selector=f_edges, wait=True)
def _normalize_rel_path(abs_path: str, vault_root: str) -> str:
@@ -130,9 +119,9 @@ def _normalize_rel_path(abs_path: str, vault_root: str) -> str:
return rel.replace("\\", "/").lstrip("/")
# -----------------------------------------------------------------------------
# ---------------------------------------------------------------------
# Main
# -----------------------------------------------------------------------------
# ---------------------------------------------------------------------
def main() -> None:
load_dotenv()
@@ -145,15 +134,25 @@ def main() -> None:
ap.add_argument("--embed-note", action="store_true", help="Optional: Note-Volltext einbetten")
ap.add_argument("--force-replace", action="store_true",
help="Änderungserkennung ignorieren und immer upserten (+ optional Purge)")
# NEU: Hash-Steuerung per CLI
ap.add_argument("--hash-mode", choices=["body", "frontmatter", "body+frontmatter"], default=None)
ap.add_argument("--hash-mode", choices=["body", "frontmatter", "body+frontmatter", "full"], default=None,
help="Vergleichsmodus: Body | Frontmatter | body+frontmatter (Alias: full)")
ap.add_argument("--hash-normalize", choices=["canonical", "none"], default=None)
ap.add_argument("--hash-source", choices=["parsed", "raw"], default=None,
help="Quelle für die Hash-Berechnung (Default: parsed)")
ap.add_argument("--note-scope-refs", action="store_true",
help="(Optional) erzeugt zusätzlich references:note (Default: aus)")
ap.add_argument("--debug-hash-diff", action="store_true",
help="Zeigt bei Bedarf einen kurzen Diff zwischen altem und neuem Body")
args = ap.parse_args()
note_scope_refs_env = (os.environ.get("MINDNET_NOTE_SCOPE_REFS", "false").strip().lower() == "true")
note_scope_refs = args.note_sCope_refs if hasattr(args, "note_sCope_refs") else args.note_scope_refs # defensive
note_scope_refs = note_scope_refs or note_scope_refs_env
cfg = QdrantConfig.from_env()
client = get_client(cfg)
ensure_collections(client, cfg.prefix, cfg.dim)
notes_col, chunks_col, edges_col = collections(cfg.prefix)
ensure_payload_indexes(client, cfg.prefix)
root = os.path.abspath(args.vault)
files = iter_md(root)
@@ -177,9 +176,16 @@ def main() -> None:
processed += 1
# Note-Payload (mit expliziten Hash-Parametern)
note_pl = make_note_payload(parsed, vault_root=root,
hash_mode=args.hash_mode, hash_normalize=args.hash_normalize)
# Note-Payload (inkl. Hash-Steuerung & Quelle)
note_pl = make_note_payload(
parsed,
vault_root=root,
hash_mode=args.hash_mode,
hash_normalize=args.hash_normalize,
hash_source=args.hash_source,
file_path=path,
)
if "fulltext" not in (note_pl or {}):
note_pl["fulltext"] = parsed.body or ""
if note_pl.get("path"):
@@ -191,46 +197,53 @@ def main() -> None:
note_id = note_pl["note_id"]
# Change-Detection
# Change-Detection (nur Inhalte, keine FS-Timestamps)
old_payload = None if args.force_replace else fetch_existing_note_payload(client, cfg.prefix, note_id)
old_hash = None if not old_payload else old_payload.get("hash_fulltext")
new_hash = note_pl.get("hash_fulltext")
old_hash = None if args.force_replace else fetch_existing_note_hash(client, cfg.prefix, note_id)
changed = args.force_replace or (old_hash != new_hash)
# Optionales Debugging: kompakten Diff anzeigen
if args.debug_hash_diff:
old_text = (old_payload or {}).get("fulltext") or ""
new_text = note_pl.get("fulltext") or ""
# Wenn Hash gleich, aber Text verschieden → Hinweis auf Normalisierung/Quelle
if (old_hash == new_hash) and old_text != new_text:
print(json.dumps({
"debug": "hash_equal_but_text_differs",
"note_id": note_id,
"hash_mode": args.hash_mode or os.environ.get("MINDNET_HASH_MODE") or os.environ.get("MINDNET_HASH_COMPARE", "body"),
"hash_normalize": args.hash_normalize or os.environ.get("MINDNET_HASH_NORMALIZE", "canonical"),
"hash_source": args.hash_source or os.environ.get("MINDNET_HASH_SOURCE", "parsed"),
}, ensure_ascii=False))
if old_text and new_text:
ud = list(difflib.unified_diff(
old_text.splitlines(), new_text.splitlines(),
fromfile="qdrant_fulltext(old)", tofile="vault_body(new)",
n=3
))
if ud:
preview = "\n".join(ud[:50])
print(json.dumps({"note_id": note_id, "diff_preview": preview}, ensure_ascii=False))
# Chunks + Embeddings (Nullvektor-Fallback)
chunks = assemble_chunks(fm["id"], parsed.body, fm.get("type", "concept"))
chunk_pls = make_chunk_payloads(fm, note_pl["path"], chunks)
if embed_texts:
vecs = embed_texts([getattr(c, "text", "") for c in chunks])
vecs = embed_texts([getattr(c, "text", "") for c in chunks]) # type: ignore[attr-defined]
else:
vecs = [[0.0] * cfg.dim for _ in chunks]
# Edges (leichtgewichtig direkt hier ableiten)
# belongs_to / prev/next aus Chunk-Nachbarschaften + Wikilinks als references
edges: List[Dict] = []
for ch in chunk_pls:
cid = ch["id"]
edges.append({"src_id": cid, "dst_id": note_id, "edge_type": "belongs_to", "scope": "chunk"})
nb = ch.get("neighbors") or {}
if nb.get("prev"):
edges.append({"src_id": nb["prev"], "dst_id": cid, "edge_type": "next", "scope": "chunk"})
edges.append({"src_id": cid, "dst_id": nb["prev"], "edge_type": "prev", "scope": "chunk"})
if nb.get("next"):
edges.append({"src_id": cid, "dst_id": nb["next"], "edge_type": "next", "scope": "chunk"})
edges.append({"src_id": nb["next"], "dst_id": cid, "edge_type": "prev", "scope": "chunk"})
for ref in (ch.get("references") or []):
tid = ref.get("target_id")
if tid:
edges.append({"src_id": cid, "dst_id": tid, "edge_type": "references", "scope": "chunk"})
for tid in (note_pl.get("references") or []):
edges.append({"src_id": note_id, "dst_id": tid, "edge_type": "references", "scope": "note"})
edges.append({"src_id": tid, "dst_id": note_id, "edge_type": "backlink", "scope": "note"})
# Dedupe
_uniq = {}
for e in edges:
_uniq[(e["src_id"], e["dst_id"], e["edge_type"], e.get("scope", ""))] = e
edges = list(_uniq.values())
# Edges (neues Schema, mit note_id als Owner)
note_refs = note_pl.get("references") or []
edges = build_edges_for_note(
note_id,
chunk_pls,
note_refs,
include_note_scope_refs=note_scope_refs,
)
# Zusammenfassung
# Zusammenfassung pro Datei
summary = {
"note_id": note_id,
"title": fm.get("title"),
@@ -241,10 +254,9 @@ def main() -> None:
"apply-skip-unchanged" if args.apply and not changed else
"dry-run"),
"path": note_pl["path"],
"hash_mode": args.hash_mode or os.environ.get("MINDNET_HASH_MODE", "body"),
"hash_mode": args.hash_mode or os.environ.get("MINDNET_HASH_MODE") or os.environ.get("MINDNET_HASH_COMPARE", "body"),
"hash_normalize": args.hash_normalize or os.environ.get("MINDNET_HASH_NORMALIZE", "canonical"),
"hash_old": old_hash,
"hash_new": new_hash,
"hash_source": args.hash_source or os.environ.get("MINDNET_HASH_SOURCE", "parsed"),
}
print(json.dumps(summary, ensure_ascii=False))
@@ -254,6 +266,7 @@ def main() -> None:
if changed and args.purge_before_upsert:
purge_note_artifacts(client, cfg.prefix, note_id)
# Upserts
notes_name, note_pts = points_for_note(cfg.prefix, note_pl, None, cfg.dim)
upsert_batch(client, notes_name, note_pts)
+185
View File
@@ -0,0 +1,185 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Script: scripts/verify_chunk_texts.py
Version: 1.0.0
Datum: 2025-09-09
Kurzbeschreibung
---------------
Verifiziert, dass in Qdrant für jede Note die zugehörigen Chunks ein Textfeld
enthalten und der Body (notes.payload.fulltext) aus den Chunk-Texten sinnvoll
rekonstruiert werden kann.
Prüfungen pro Note:
- Alle Chunks vorhanden (>=1).
- Jedes Chunk-Payload hat einen nutzbaren Textschlüssel: "text" (bevorzugt), sonst "content", sonst "raw".
- Reihenfolge der Chunks wird stabil bestimmt (payload.chunk_index -> Nummer aus chunk_id).
- Coverage: Summe der im Fulltext gefundenen Chunk-Textsegmente / len(Fulltext) (Toleranz für Overlaps).
-> OK wenn coverage >= 0.90 (konfigurierbar via --min-coverage)
Ausgabe:
- JSON mit Gesamtsummen und Details je Note.
ENV:
- QDRANT_URL | QDRANT_HOST/QDRANT_PORT | QDRANT_API_KEY
- COLLECTION_PREFIX (Fallback, wenn --prefix fehlt)
Beispiele:
# Alle Notes prüfen (Prefix aus ENV)
python3 -m scripts.verify_chunk_texts
# Nur eine Note prüfen
python3 -m scripts.verify_chunk_texts --note-id concept-alpha
# Prefix explizit setzen und strengere Coverage verlangen
python3 -m scripts.verify_chunk_texts --prefix mindnet --min-coverage 0.95
"""
from __future__ import annotations
import argparse, json, os, re, sys
from typing import Dict, List, Tuple, Optional
from qdrant_client import QdrantClient
from qdrant_client.http import models as rest
def _names(prefix: str) -> Tuple[str,str,str]:
return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges"
def _client() -> QdrantClient:
url = os.getenv("QDRANT_URL")
if not url:
host = os.getenv("QDRANT_HOST", "127.0.0.1")
port = int(os.getenv("QDRANT_PORT", "6333"))
url = f"http://{host}:{port}"
api_key = os.getenv("QDRANT_API_KEY") or None
return QdrantClient(url=url, api_key=api_key)
def _chunk_sort_key(p: Dict, pid: str) -> Tuple[int,int,str]:
# Primär: payload.chunk_index, sekundär: Nummer am Ende der ID (#cNN oder #NN), sonst 0
ci = p.get("chunk_index")
n = 0
m = re.search(r'#c?(\d+)$', pid or "")
if m:
try:
n = int(m.group(1))
except Exception:
n = 0
return (ci if isinstance(ci, int) else 1_000_000 + n, n, pid)
def _choose_text(payload: Dict) -> Optional[str]:
for k in ("text", "content", "raw"):
v = payload.get(k)
if isinstance(v, str) and v.strip():
return v
return None
def _coverage(fulltext: str, pieces: List[str]) -> float:
"""Berechnet die Abdeckungsquote der Stücke im Fulltext (sequenzielles Matching)."""
if not fulltext:
return 0.0 if pieces else 1.0
cursor = 0
covered = 0
ft = fulltext
for piece in pieces:
if not piece:
continue
# Tolerant gegen Whitespace-Unterschiede: normalisieren nur \r\n→\n
p = piece.replace("\r\n", "\n").replace("\r", "\n")
idx = ft.find(p, cursor)
if idx == -1:
# Versuche ein paar Heuristiken: trimmen
p2 = p.strip()
if p2 and len(p2) > 8:
idx = ft.find(p2, cursor)
if idx != -1:
covered += len(p)
cursor = idx + len(p)
# sonst: nicht abgedeckt
return covered / max(1, len(ft))
def main() -> None:
ap = argparse.ArgumentParser()
ap.add_argument("--prefix", help="Collection-Prefix (Default: ENV COLLECTION_PREFIX oder 'mindnet')")
ap.add_argument("--note-id", help="Nur eine bestimmte Note prüfen")
ap.add_argument("--min-coverage", type=float, default=0.90, help="Mindestabdeckung durch Chunks (Default: 0.90)")
args = ap.parse_args()
prefix = args.prefix or os.getenv("COLLECTION_PREFIX", "mindnet")
notes_col, chunks_col, _ = _names(prefix)
cli = _client()
# Notes abrufen (optional filter by note_id)
notes_filter = None
if args.note_id:
notes_filter = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=args.note_id))])
notes: List[Dict] = []
off = None
while True:
pts, off = cli.scroll(collection_name=notes_col, scroll_filter=notes_filter,
with_payload=True, with_vectors=False, limit=256, offset=off)
if not pts:
break
for p in pts:
notes.append({"id": p.id, "payload": p.payload or {}})
if off is None:
break
results = []
total_missing_text = 0
total_notes_ok = 0
for n in notes:
pl = n["payload"]
nid = pl.get("note_id") or pl.get("id") or n.get("id")
fulltext = pl.get("fulltext") or ""
# Chunks der Note holen
f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=nid))])
chunks = []
off = None
while True:
pts, off = cli.scroll(collection_name=chunks_col, scroll_filter=f,
with_payload=True, with_vectors=False, limit=256, offset=off)
if not pts:
break
for p in pts:
chunks.append({"id": p.id, "payload": p.payload or {}})
if off is None:
break
# sortieren
chunks.sort(key=lambda c: _chunk_sort_key(c["payload"], c["id"]))
texts = []
missing_text = 0
for c in chunks:
t = _choose_text(c["payload"])
if t is None:
missing_text += 1
texts.append("")
else:
texts.append(t)
cov = _coverage(fulltext, texts)
ok = (missing_text == 0) and (cov >= args.min_coverage or not fulltext)
if ok:
total_notes_ok += 1
total_missing_text += missing_text
results.append({
"note_id": nid,
"title": pl.get("title"),
"chunks": len(chunks),
"missing_chunk_texts": missing_text,
"coverage": round(cov, 4),
"has_fulltext": bool(fulltext),
"ok": ok
})
out = {
"collections": {"notes": notes_col, "chunks": chunks_col},
"notes_checked": len(notes),
"notes_ok": total_notes_ok,
"total_missing_chunk_texts": total_missing_text,
"min_coverage": args.min_coverage,
"details": results
}
print(json.dumps(out, ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()