Compare commits

...
Author SHA1 Message Date
Lars 0a891cfd95 docs/knowledge_design.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-10-06 18:33:42 +02:00
Lars 66adc6a354 docs/Handbuch.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 2s
2025-10-06 14:22:47 +02:00
Lars e99f1c2ba0 tests/compare_vaults.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 7s
2025-10-06 13:29:00 +02:00
Lars f52a9face8 app/core/chunk_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-10-06 12:35:54 +02:00
Lars 4fcf22131c tests/check_chunks_window_vs_text.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 2s
2025-10-01 15:25:17 +02:00
Lars d27324f8dd tests/check_chunks_vs_text.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-10-01 15:23:08 +02:00
Lars dd86a15555 app/core/chunk_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-10-01 15:20:10 +02:00
Lars 28d173b8fd app/core/parser.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-10-01 12:08:50 +02:00
Lars b4b7ea76ab app/core/parser.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-10-01 10:58:23 +02:00
Lars 6ea452cc3f app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-10-01 10:54:46 +02:00
Lars 6e0e965883 tests/inspect_one_note.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-10-01 10:27:15 +02:00
Lars 6b4b3ce2ba tests/list_md_seen_by_importer.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-10-01 10:24:25 +02:00
Lars 18cdbab885 scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-09-30 15:50:38 +02:00
Lars ebca9b4caf scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-09-30 15:45:31 +02:00
Lars 6945ef8ddc scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-09-30 15:39:55 +02:00
Lars f20bf03ee1 tests/audit_edges_now.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-09-30 12:37:56 +02:00
Lars 7cda15553d app/core/derive_edges.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-09-30 12:36:19 +02:00
Lars 3c67fd5f9b app/core/chunk_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-09-30 12:26:33 +02:00
Lars 0150931df4 scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-09-30 12:22:07 +02:00
Lars 5ff1b06009 scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-09-30 12:19:12 +02:00
Lars 5279bcae18 app/core/chunk_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-09-30 12:18:16 +02:00
Lars daa58e6b27 tests/verify_chunks_integrity.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-09-30 12:09:18 +02:00
Lars 589d021744 tests/verify_chunks_integrity.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-09-30 12:05:13 +02:00
Lars e58b9c8ada scripts/export_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-09-30 10:54:36 +02:00
Lars 507c28e006 tests/compare_vaults.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 2s
2025-09-29 16:07:22 +02:00
Lars 2d74fe4057 .gitea/workflows/deploy.yml aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 9s
2025-09-29 15:41:20 +02:00
Lars e8312268d2 .gitea/workflows/deploy.yml aktualisiert 2025-09-29 15:35:27 +02:00
Lars f4cd1e51c0 tests/compare_vaults.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 1s
2025-09-24 12:35:53 +02:00
Lars 60e707e7df .gitea/workflows/deploy.yml aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 1s
2025-09-24 12:35:20 +02:00
Lars 0d6eb4dac4 tests/compare_vaults.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Failing after 1s
2025-09-24 12:34:53 +02:00
Lars 80d8f986bd tests/test_importer_detect_changes.sh hinzugefügt
Deploy mindnet to llm-node / deploy (push) Failing after 1s
2025-09-24 12:34:22 +02:00
Lars 9ee3bb9007 tests/run_e2e_roundtrip.sh hinzugefügt
Deploy mindnet to llm-node / deploy (push) Failing after 1s
2025-09-24 12:33:55 +02:00
Lars 8a07010704 app/graph/service.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Failing after 1s
2025-09-24 12:17:02 +02:00
Lars 314fc8ac94 scripts/debug_qdrant_state.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Failing after 1s
2025-09-24 12:16:35 +02:00
Lars b46e5461a7 scripts/report_hashes.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Failing after 1s
2025-09-24 12:16:05 +02:00
Lars ada7c1797d scripts/export_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-24 12:15:34 +02:00
Lars 54197995f5 scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-24 12:14:56 +02:00
Lars 13e510dd9c scripts/export_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 1s
2025-09-24 12:14:30 +02:00
Lars 5c937fbffe scripts/export_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-24 12:13:04 +02:00
Lars 58bce0ea19 scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 19:57:32 +02:00
Lars 3e888cc669 scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 19:47:16 +02:00
Lars 78446c74d3 schemas/note.schema.json aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 19:43:12 +02:00
Lars 51f08f193c scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 19:42:35 +02:00
Lars 4872374a6e app/core/note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 19:42:09 +02:00
Lars 81c1400ef4 app/core/note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:55:36 +02:00
Lars 298c1fb180 scripts/debug_note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:55:12 +02:00
Lars f8108bd724 scripts/debug_note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:52:25 +02:00
Lars 65c40b287f scripts/debug_note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:48:41 +02:00
Lars 13e50d4695 scripts/debug_note_payload.py hinzugefügt
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:47:13 +02:00
Lars 791cda23af scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:44:59 +02:00
Lars 466ea64e63 scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:39:48 +02:00
Lars f5e6fcc097 scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:36:27 +02:00
Lars 9ef2e8d397 app/core/note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:33:38 +02:00
Lars 4637091125 app/core/note_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:31:25 +02:00
Lars 43a8c80508 scripts/import_markdown.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:31:00 +02:00
Lars 9362064ad1 scripts/make_test_vault.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:17:27 +02:00
Lars 23952aa3c5 app/core/chunk_payload.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:16:34 +02:00
Lars 79e19c85eb schemas/note.schema.json aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:15:53 +02:00
Lars 62d8299480 schemas/edge.schema.json aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:15:22 +02:00
Lars 8f342ea2d3 schemas/chunk.schema.json aktualisiert
Deploy mindnet to llm-node / deploy (push) Failing after 2s
2025-09-09 16:15:05 +02:00
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
30 changed files with 3664 additions and 1482 deletions

No files matched your search

+31 -12
View File
@@ -1,22 +1,36 @@
# .gitea/workflows/deploy.yml # .gitea/workflows/deploy.yml
name: Deploy mindnet to llm-node name: Deploy mindnet to llm-node
on: { push: { branches: [ "main" ] } }
# on: {}
concurrency: { group: deploy-mindnet, cancel-in-progress: false } on:
push:
branches: ["main"]
concurrency:
group: deploy-mindnet
cancel-in-progress: false
jobs: jobs:
deploy: deploy:
runs-on: linux_host runs-on: linux_host
env: env:
DEPLOY_DIRS: "app scripts schemas docker requirements.txt README.md" TARGET_BASE: /home/llmadmin/mindnet
TARGET_BASE: "/home/llmadmin/mindnet" DEPLOY_DIRS: "app scripts schemas docker tests requirements.txt README.md"
steps: steps:
- name: Checkout - name: Checkout
uses: https://github.com/actions/checkout@v4 uses: actions/checkout@v4
- name: Ensure target base
- name: Ensure target base exists
run: install -d "$TARGET_BASE" run: install -d "$TARGET_BASE"
- name: Deploy whitelisted
- name: Stop API (graceful)
continue-on-error: true
run: |
if systemctl --user list-unit-files | grep -q '^mindnet-api.service'; then
systemctl --user stop mindnet-api.service || true
fi
- name: Deploy whitelisted (rsync)
run: | run: |
set -euo pipefail set -euo pipefail
IFS=' ' read -r -a DIRS <<< "$DEPLOY_DIRS" IFS=' ' read -r -a DIRS <<< "$DEPLOY_DIRS"
@@ -24,22 +38,27 @@ jobs:
if [ -e "$d" ]; then if [ -e "$d" ]; then
if [ -d "$d" ]; then if [ -d "$d" ]; then
install -d "$TARGET_BASE/$d" install -d "$TARGET_BASE/$d"
rsync -a --delete --exclude='.git' \ rsync -a --delete \
--exclude='.env' --exclude='.env.*' --exclude='**/.env*' \ --exclude='.git' \
--exclude='.env*' \
--exclude='.venv' \
--exclude='hf_cache' --exclude='hf_cache/**' \
"$d"/ "$TARGET_BASE/$d"/ "$d"/ "$TARGET_BASE/$d"/
else else
rsync -a "$d" "$TARGET_BASE/$d" rsync -a "$d" "$TARGET_BASE/$d"
fi fi
fi fi
done done
- name: Python venv (idempotent)
- name: Python venv & requirements
run: | run: |
cd "$TARGET_BASE" cd "$TARGET_BASE"
[ -d .venv ] || python3 -m venv .venv [ -d .venv ] || python3 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
pip install --upgrade pip pip install --upgrade pip
[ -f requirements.txt ] && pip install -r requirements.txt || true [ -f requirements.txt ] && pip install -r requirements.txt || true
- name: Optional — restart mindnet-api
- name: Start/Restart mindnet-api
continue-on-error: true continue-on-error: true
run: | run: |
if systemctl --user list-unit-files | grep -q '^mindnet-api.service'; then if systemctl --user list-unit-files | grep -q '^mindnet-api.service'; then
+249 -137
View File
@@ -2,158 +2,270 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """
Modul: app/core/chunk_payload.py Modul: app/core/chunk_payload.py
Version: 1.1.3 Version: 2.2.0
Datum: 2025-09-09 Datum: 2025-10-06
Kurzbeschreibung Zweck
---------------- -----
Erzeugt Qdrant-Payloads für Text-Chunks einer Note. Jeder Chunk enthält Erzeugt Qdrant-Payloads für Chunks. Voll abwärtskompatibel zu v2.0.1.
den tatsächlichen Text unter dem Schlüssel ``text``. Dadurch kann der Neu: Wenn der Chunker KEIN Overlap im Fenster liefert (== window fehlt / identisch zur Kernpassage),
Exporter den vollständigen Body verlässlich aus Chunks rekonstruieren, erzeugen wir FENSTER mit synthetischem Overlap auf Basis chunk_config.get_sizes(note_type)['overlap'].
falls ``notes.payload.fulltext`` fehlt.
Wesentliche Features Felder (beibehalten aus 2.0.1):
-------------------- - note_id, chunk_id, id (Alias), chunk_index, seq, path
- Stabile, idempotente Payload-Struktur für Chunks - window (mit Overlap), text (ohne linkes Overlap)
- Persistenter Chunk-Text (``text``) - start, end (Offsets im gesamten Body)
- Extraktion von Wikilinks pro Chunk (``wikilinks`` & ``references``) - overlap_left, overlap_right
- Pfadübernahme (relativ zum Vault, wird vom Aufrufer geliefert) - token_count?, section_title?, section_path?, type?, title?, tags?
- Bereinigung leerer Felder (keine ``None``/leere Collections im Payload)
Abhängigkeiten Kompatibilität:
-------------- - 'id' == 'chunk_id' als Alias
- ``app.core.chunker.Chunk`` und ``assemble_chunks`` (nur für CLI-Demo) - Pfade bleiben relativ (keine führenden '/'), Backslashes → Slashes
- ``app.core.parser.extract_wikilinks`` und ``read_markdown`` (nur CLI-Demo) - Robust für Chunk-Objekte oder Dicts; Fensterquelle: 'window'|'text'|'content'|'raw'
Beispiele (CLI – Sichtprüfung) Lizenz: MIT (projektintern)
------------------------------
python3 -m app.core.chunk_payload --from-file ./vault/demo.md --print
""" """
from __future__ import annotations from __future__ import annotations
from typing import Dict, List, Any
import argparse
import json
import os
# WICHTIG: Keine direkten Selbst- oder Kreuz-Imports, die Zyklen erzeugen! from typing import Any, Dict, Iterable, List, Optional, Tuple, Union
# Für die Kernfunktion reicht extract_wikilinks als Typ-unabhängige Hilfsfunktion.
try: try:
from app.core.parser import extract_wikilinks # nur Funktion, erzeugt keine Zyklen # Typgerechtes Overlap aus deiner Konfiguration holen
except Exception: # pragma: no cover from app.core.chunk_config import get_sizes as _get_sizes
from .parser import extract_wikilinks # type: ignore except Exception:
def _get_sizes(_note_type: str):
# Typ-Hinweis für Chunk (zur Laufzeit nicht notwendig) # konservativer Default, falls Import fehlschlägt
try: return {"overlap": (40, 60), "target": (250, 350), "max": 500}
from app.core.chunker import Chunk # nur Typ-Annotation / Nutzung im CLI
except Exception: # pragma: no cover
class Chunk: # type: ignore
pass
# --------------------------------------------------------------------------- # ------------------------------- Utils ------------------------------- #
# Utils
# ---------------------------------------------------------------------------
def _drop_empty(d: Dict[str, Any]) -> Dict[str, Any]: def _get_attr_or_key(obj: Any, key: str, default=None):
"""Entfernt leere/None-Felder aus einem Dict (für saubere Payloads).""" if obj is None:
return {k: v for k, v in d.items() if v not in (None, [], {}, "")} return default
if isinstance(obj, dict):
return obj.get(key, default)
return getattr(obj, key, default)
def _as_window_text(chunk: Any) -> str:
"""Fenstertext robust lesen (bevorzugt echte Fenster, sonst Kern)."""
for k in ("window", "text", "content", "raw"):
v = _get_attr_or_key(chunk, k, None)
if isinstance(v, str) and v:
return v
return ""
# --------------------------------------------------------------------------- def _to_int(x: Any, default: int = 0) -> int:
# Kernfunktion
# ---------------------------------------------------------------------------
def make_chunk_payloads(note_meta: Dict[str, Any], path: str, chunks: List[Chunk]) -> List[Dict[str, Any]]:
"""
Baut Payloads für alle ``chunks`` der gegebenen Note.
Parameters
----------
note_meta : Dict[str, Any]
Minimale Metadaten der Note (mind. ``id``, ``title``; optional ``type``,
``area``, ``project``, ``tags``, ``lang``).
path : str
Relativer Pfad der Note innerhalb des Vaults (z. B. "area/topic/file.md").
chunks : List[Chunk]
Liste vorsegmentierter Chunks (vgl. app.core.chunker.Chunk).
Returns
-------
List[Dict[str, Any]]
Payload-Objekte, bereit für Qdrant-Upserts.
"""
res: List[Dict[str, Any]] = []
for ch in chunks:
# 'text' kann bei leerem Abschnitt None/'' sein → robust behandeln
text_val = getattr(ch, "text", "") or ""
wikilinks = extract_wikilinks(text_val)
payload = {
"id": getattr(ch, "id", None),
"note_id": note_meta.get("id"),
"note_title": note_meta.get("title"),
"chunk_index": getattr(ch, "index", None),
"char_start": getattr(ch, "char_start", None),
"char_end": getattr(ch, "char_end", None),
"token_count": getattr(ch, "token_count", None),
"section_title": getattr(ch, "section_title", None),
"section_path": getattr(ch, "section_path", None),
"lang": note_meta.get("lang"),
"wikilinks": wikilinks,
"external_links": [],
"references": [{"target_id": w, "kind": "wikilink"} for w in wikilinks],
"neighbors": {
"prev": getattr(ch, "neighbors_prev", None),
"next": getattr(ch, "neighbors_next", None),
},
"path": path, # vom Aufrufer relativ geliefert
"text": text_val, # WICHTIG für Export/Rekonstruktion
}
res.append(_drop_empty(payload))
return res
# ---------------------------------------------------------------------------
# CLI – nur zur Sichtprüfung / Debug
# ---------------------------------------------------------------------------
def _cli() -> None:
# CLI lädt hier *lazy* die schweren Abhängigkeiten,
# damit die Modul-Initialisierung zirkularfrei bleibt.
try: try:
from app.core.parser import read_markdown return int(x)
from app.core.chunker import assemble_chunks except Exception:
except Exception: # pragma: no cover return default
from .parser import read_markdown # type: ignore
from .chunker import assemble_chunks # type: ignore
ap = argparse.ArgumentParser(description="Vorschau: Chunk-Payloads erzeugen und anzeigen") def _normalize_rel_path(p: str) -> str:
ap.add_argument("--from-file", dest="src", required=True, help="Pfad zu einer Markdown-Datei") p = (p or "").replace("\\", "/")
ap.add_argument("--print", dest="do_print", action="store_true", help="Payload auf stdout ausgeben") while p.startswith("/"):
args = ap.parse_args() p = p[1:]
return p
note = read_markdown(args.src)
note_meta = {
"id": note.frontmatter.get("id") or note.frontmatter.get("note_id"),
"title": note.frontmatter.get("title"),
"type": note.frontmatter.get("type"),
"area": note.frontmatter.get("area"),
"project": note.frontmatter.get("project"),
"tags": note.frontmatter.get("tags", []),
"lang": note.frontmatter.get("lang"),
}
chunks = assemble_chunks(note.frontmatter.get("id"), note.body or "", note.frontmatter.get("type", "concept"))
# Vault-Root heuristisch relativieren (nur für Demo)
vault_root = os.path.dirname(os.path.dirname(args.src)) # heuristisch
rel_path = os.path.relpath(args.src, vault_root).replace("\\", "/").lstrip("/")
payloads = make_chunk_payloads(note_meta, rel_path, chunks)
if args.do_print:
print(json.dumps(payloads, ensure_ascii=False, indent=2))
# ---------------------- Overlap & Offsets ---------------------------- #
def _dedupe_windows_to_segments(windows: List[str]) -> Tuple[List[str], List[int], str]:
"""
Entfernt linkes Overlap aus echten Fenster-Strings.
Rückgabe: (segments, overlaps_left, reconstructed_text)
"""
segments: List[str] = []
overlaps_left: List[int] = []
reconstructed = ""
for w in windows:
w = w or ""
max_k = min(len(w), len(reconstructed))
k = 0
for cand in range(max_k, -1, -1):
if reconstructed.endswith(w[:cand]):
k = cand
break
seg = w[k:]
segments.append(seg)
overlaps_left.append(k)
reconstructed += seg
return segments, overlaps_left, reconstructed
def _overlap_len_suffix_prefix(a: str, b: str, max_probe: int = 4096) -> int:
"""Länge längsten Suffix(a), der Prefix(b) ist."""
if not a or not b:
return 0
a1 = a[-max_probe:]
b1 = b[:max_probe]
n = min(len(a1), len(b1))
for k in range(n, 0, -1):
if a1[-k:] == b1[:k]:
return k
return 0
# ----------------------------- Public API ---------------------------- #
def make_chunk_payloads(
frontmatter: Dict[str, Any],
rel_path: str,
chunks: Iterable[Union[Dict[str, Any], Any]],
note_text: Optional[str] = None,
) -> List[Dict[str, Any]]:
"""
Baut Payloads pro Chunk. Falls Fenster ohne Overlap geliefert werden,
erzeugen wir synthetische 'window'-Texte mit typgerechtem Overlap.
"""
note_id = str(frontmatter.get("id") or "").strip()
note_type = str(frontmatter.get("type", "")).lower()
note_title = frontmatter.get("title", None)
note_tags = frontmatter.get("tags", None)
rel_path = _normalize_rel_path(rel_path)
# 1) Rohdaten sammeln (so wie geliefert)
chunks_list = list(chunks)
raw_windows: List[str] = []
seqs: List[int] = []
ids_in: List[Optional[str]] = []
token_counts: List[Optional[int]] = []
section_titles: List[Optional[str]] = []
section_paths: List[Optional[str]] = []
any_explicit_window = False
for idx, c in enumerate(chunks_list):
# Fensterquelle
w = _get_attr_or_key(c, "window", None)
if isinstance(w, str) and w:
any_explicit_window = True
raw_windows.append(w)
else:
raw_windows.append(_as_window_text(c)) # 'text'|'content'|'raw' als Ersatz
# Ordnung
seqs.append(_to_int(_get_attr_or_key(c, "seq", _get_attr_or_key(c, "chunk_index", idx)), idx))
# IDs, Tokens, Sektionen
cid = _get_attr_or_key(c, "chunk_id", _get_attr_or_key(c, "id", None))
ids_in.append(str(cid) if isinstance(cid, str) and cid else None)
tc = _get_attr_or_key(c, "token_count", None)
token_counts.append(_to_int(tc, 0) if tc is not None else None)
section_titles.append(_get_attr_or_key(c, "section_title", None))
section_paths.append(_get_attr_or_key(c, "section_path", None))
# 2) Segmente & Overlaps bestimmen
if any_explicit_window:
# Es existieren echte Fenster → dedupe, um Kernsegmente zu finden
segments, overlaps_left, recon = _dedupe_windows_to_segments(raw_windows)
windows_final = raw_windows[:] # bereits mit Overlap geliefert
else:
# Keine echten Fenster → Segmente sind identisch zu "Fenstern" (bisher),
# wir erzeugen synthetische Fenster mit Overlap gemäß Typ
segments = [w or "" for w in raw_windows]
overlaps_left = []
windows_final = []
recon = ""
try:
overlap_low, overlap_high = tuple(_get_sizes(note_type).get("overlap", (40, 60)))
except Exception:
overlap_low, overlap_high = (40, 60)
overlap_target = int(overlap_low)
for i, seg in enumerate(segments):
if i == 0:
# erstes Fenster: kein linker Kontext
windows_final.append(seg)
overlaps_left.append(0)
recon += seg
else:
# synthetischer linker Kontext = Suffix des bisher rekonstruierten Texts
k = min(overlap_target, len(recon))
left_ctx = recon[-k:] if k > 0 else ""
windows_final.append(left_ctx + seg)
overlaps_left.append(k)
recon += seg # Rekonstruktion bleibt kerntreu
# 3) overlap_right bestimmen
overlaps_right: List[int] = []
for i in range(len(windows_final)):
if i + 1 < len(windows_final):
ov = _overlap_len_suffix_prefix(windows_final[i], windows_final[i + 1], max_probe=4096)
else:
ov = 0
overlaps_right.append(ov)
# 4) start/end-Offsets (exakt via note_text, sonst kumulativ)
starts: List[int] = [0] * len(segments)
ends: List[int] = [0] * len(segments)
pos = 0
if isinstance(note_text, str) and note_text:
search_pos = 0
for i, seg in enumerate(segments):
if not seg:
starts[i] = ends[i] = search_pos
continue
j = note_text.find(seg, search_pos)
if j >= 0:
starts[i] = j
ends[i] = j + len(seg)
search_pos = ends[i]
else:
# Fallback: kumulativ
starts[i] = pos
pos += len(seg)
ends[i] = pos
else:
for i, seg in enumerate(segments):
starts[i] = pos
pos += len(seg)
ends[i] = pos
# 5) Payload-Dicts
payloads: List[Dict[str, Any]] = []
for i, (win, seg) in enumerate(zip(windows_final, segments)):
chunk_id = ids_in[i] or f"{note_id}#{i+1}"
pl: Dict[str, Any] = {
"note_id": note_id,
"chunk_id": chunk_id,
"id": chunk_id, # Alias
"chunk_index": i,
"seq": seqs[i],
"path": rel_path,
"window": win,
"text": seg,
"start": starts[i],
"end": ends[i],
"overlap_left": overlaps_left[i],
"overlap_right": overlaps_right[i],
}
# optionale Metadaten
if note_type:
pl["type"] = note_type
if note_title is not None:
pl["title"] = note_title
if note_tags is not None:
pl["tags"] = note_tags
if token_counts[i] is not None:
pl["token_count"] = int(token_counts[i])
if section_titles[i] is not None:
pl["section_title"] = section_titles[i]
if section_paths[i] is not None:
sp = str(section_paths[i]).replace("\\", "/")
pl["section_path"] = sp if sp else "/"
payloads.append(pl)
return payloads
# __main__ Demo (optional)
if __name__ == "__main__": # pragma: no cover if __name__ == "__main__": # pragma: no cover
_cli() fm = {"id": "demo", "title": "Demo", "type": "concept"}
# Beispiel ohne echte Fenster → erzeugt synthetische Overlaps
chunks = [
{"id": "demo#1", "text": "Alpha Beta Gamma"},
{"id": "demo#2", "text": "Gamma Delta"},
{"id": "demo#3", "text": "Delta Epsilon Zeta"},
]
pls = make_chunk_payloads(fm, "path/demo.md", chunks, note_text="Alpha Beta Gamma Delta Epsilon Zeta")
from pprint import pprint
pprint(pls)
recon = "".join(p["text"] for p in pls)
print("RECON:", recon)
+114 -109
View File
@@ -1,126 +1,131 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """
Name: app/core/derive_edges.py Modul: app/core/derive_edges.py
Version: v1.1.0 (2025-09-05) Version: 1.4.0
Datum: 2025-10-01
Kurzbeschreibung Zweck
Leitet Edges aus Wikilinks ([[…]]) ab und löst Zielnoten robust auf. -----
Erzeugt: Robuste Kantenbildung für mindnet (Notes/Chunks):
- "references" (Note -> Note) mit seq="body", pro Match eine eigene Occurrence 'occ' - belongs_to (chunk -> note)
- "backlink" (inverse zu "references", gleiche seq/occ) - next / prev (chunk-Kette)
- "references_at" (Chunk -> Note) mit seq=<chunk_index> und eigener 'occ' je Match - references (chunk-scope) aus Chunk.window/text
- optional references/backlink (note-scope)
Aufruf Wichtig: Wikilinks werden mit der Parser-Funktion `extract_wikilinks` extrahiert,
from app.core.derive_edges import build_note_index, derive_wikilink_edges damit Varianten wie [[id#anchor]] oder [[id|label]] korrekt auf 'id' reduziert werden.
Parameter / Felder Erwartete Chunk-Payload-Felder:
- note_payload: {"note_id","title","path","fulltext": <body> , …} {
- chunks_payloads: [{"chunk_id","text",…}, …] "note_id": "...",
- note_index: build_note_index([...]) -> (by_id, by_slug, by_file_slug) "chunk_id": "...", # Alias "id" ist zulässig
"id": "...",
Kompatibilität "chunk_index": int,
- Rückwärtskompatible Payload-Felder, nur erweitert um 'seq' und 'occ'. "seq": int,
"window": str,
Changelog "text": str,
v1.1.0: Occurrence-Zählung ('occ') je Match; 'seq="body"' für references. "path": "rel/path.md",
...
}
""" """
from __future__ import annotations from __future__ import annotations
import re
import unicodedata
from typing import Dict, List, Tuple
# [[Ziel]], [[Ziel|Alias]], [[Ziel#Heading]], [[Ziel#Heading|Alias]] from typing import Dict, List, Optional, Iterable
WIKILINK_RE = re.compile(r"\[\[([^\]|#]+)(?:#([^\]|]+))?(?:\|([^\]]+))?\]\]")
def _slug(s: str) -> str: # WICHTIG: benutze die Parser-Extraktion für saubere Wikilinks
s = s.strip() from app.core.parser import extract_wikilinks
if s.endswith(".md"):
s = s[:-3]
s = unicodedata.normalize("NFKD", s)
s = "".join(ch for ch in s if not unicodedata.combining(ch))
s = s.replace("\\", "/")
s = s.split("/")[-1]
s = s.lower().replace(" ", "-")
s = re.sub(r"[^a-z0-9\-]+", "", s)
s = re.sub(r"-{2,}", "-", s).strip("-")
return s
def build_note_index(notes_payloads: List[dict]) -> Tuple[Dict[str, dict], Dict[str, dict], Dict[str, dict]]: def _get(d: dict, *keys, default=None):
by_id: Dict[str, dict] = {} for k in keys:
by_slug: Dict[str, dict] = {} if k in d and d[k] is not None:
by_file_slug: Dict[str, dict] = {} return d[k]
for n in notes_payloads: return default
nid = n.get("note_id") or n.get("id")
if not nid:
continue
by_id[nid] = n
title = n.get("title", "")
path = n.get("path", "")
file_slug = _slug(path.split("/")[-1]) if path else ""
if title:
by_slug[_slug(title)] = n
if file_slug:
by_file_slug[file_slug] = n
return by_id, by_slug, by_file_slug
def resolve_target(note_like: str, idx: Tuple[Dict[str,dict],Dict[str,dict],Dict[str,dict]]): def _chunk_text_for_refs(chunk: dict) -> str:
by_id, by_slug, by_file_slug = idx # bevorzugt 'window' → dann 'text' → 'content' → 'raw'
key = note_like.strip() return (
if key in by_id: _get(chunk, "window")
return by_id[key]["note_id"], "by_id" or _get(chunk, "text")
s = _slug(key) or _get(chunk, "content")
if s in by_slug: or _get(chunk, "raw")
return by_slug[s]["note_id"], "by_slug" or ""
if s in by_file_slug: )
return by_file_slug[s]["note_id"], "by_file_slug"
return None, "unresolved"
def derive_wikilink_edges(note_payload: dict, chunks_payloads: List[dict], note_index) -> List[dict]: def _dedupe(seq: Iterable[str]) -> List[str]:
seen = set()
out: List[str] = []
for s in seq:
if s not in seen:
seen.add(s)
out.append(s)
return out
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"
"source_id": source_id,
"target_id": target_id,
"note_id": note_id, # Träger/Quelle der Kante (aktuelle Note)
}
if extra:
pl.update(extra)
return pl
def build_edges_for_note(
note_id: str,
chunks: List[dict],
note_level_references: Optional[List[str]] = None,
include_note_scope_refs: bool = False,
) -> List[dict]:
"""
Erzeugt Kanten für eine Note.
- belongs_to: für jeden Chunk (chunk -> note)
- next / prev: zwischen aufeinanderfolgenden Chunks
- references: pro Chunk aus window/text
- optional note-scope references/backlinks: dedupliziert über alle Chunk-Funde + note_level_references
"""
edges: List[dict] = [] edges: List[dict] = []
source_note_id = note_payload["note_id"]
def _make_edge(kind: str, src: str, tgt: str, seq=None, occ=None, extra: dict|None=None): # belongs_to
e = {"edge_id": None, "kind": kind, "source_id": src, "target_id": tgt} for ch in chunks:
if seq is not None: cid = _get(ch, "chunk_id", "id")
e["seq"] = seq if not cid:
if occ is not None:
e["occ"] = occ
if extra:
e.update(extra)
return e
# Volltext (Note-Ebene)
fulltext = note_payload.get("fulltext") or note_payload.get("body") or ""
if fulltext:
for k, m in enumerate(WIKILINK_RE.finditer(fulltext), start=1):
raw_target, heading, alias = m.groups()
target_id, how = resolve_target(raw_target, note_index)
extra = {"raw": raw_target, "alias": alias, "heading": heading, "resolution": how}
if target_id:
edges.append(_make_edge("references", source_note_id, target_id, seq="body", occ=k, extra=extra))
edges.append(_make_edge("backlink", target_id, source_note_id, seq="body", occ=k, extra=extra))
else:
extra["status"] = "unresolved"
extra["target_label"] = raw_target
edges.append(_make_edge("references", source_note_id, raw_target, seq="body", occ=k, extra=extra))
# Chunks (Chunk-Ebene)
for i, ch in enumerate(chunks_payloads, start=1):
txt = ch.get("text") or ch.get("content") or ""
if not txt:
continue continue
occ = 0 edges.append(_edge("belongs_to", "chunk", cid, note_id, note_id, {"chunk_id": cid}))
for m in WIKILINK_RE.finditer(txt):
occ += 1 # next/prev
raw_target, heading, alias = m.groups() for i in range(len(chunks) - 1):
target_id, how = resolve_target(raw_target, note_index) a, b = chunks[i], chunks[i + 1]
extra = {"raw": raw_target, "alias": alias, "heading": heading, "resolution": how} a_id = _get(a, "chunk_id", "id")
if target_id: b_id = _get(b, "chunk_id", "id")
edges.append(_make_edge("references_at", ch["chunk_id"], target_id, seq=i, occ=occ, extra=extra)) if not a_id or not b_id:
else: continue
extra["status"] = "unresolved" edges.append(_edge("next", "chunk", a_id, b_id, note_id, {"chunk_id": a_id}))
extra["target_label"] = raw_target edges.append(_edge("prev", "chunk", b_id, a_id, note_id, {"chunk_id": b_id}))
edges.append(_make_edge("references_at", ch["chunk_id"], raw_target, seq=i, occ=occ, extra=extra))
# references (chunk-scope) – Links aus window bevorzugen (Overlap-fest)
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, kompatibel zu deinem System
for r in refs:
edges.append(_edge("references", "chunk", cid, r, note_id, {"chunk_id": cid, "ref_text": r}))
refs_all.extend(refs)
# optional: note-scope references/backlinks
if include_note_scope_refs:
refs_note = refs_all[:]
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)
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))
return edges return edges
+108 -33
View File
@@ -1,45 +1,120 @@
from __future__ import annotations #!/usr/bin/env python3
from typing import List, Dict # -*- 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] = [] edges: List[Dict] = []
# Chunk → Note (belongs_to) + prev/next # Chunk-Scope: belongs_to / prev / next / references
for idx, ch in enumerate(chunk_payloads): for ch in chunk_payloads:
cid = ch["id"]
owner = ch.get("note_id") or note_id
# belongs_to
edges.append({ edges.append({
"src_id": ch["id"], "dst_id": note_meta["id"], "kind": "belongs_to",
"edge_type": "belongs_to", "scope": "chunk" "source_id": cid,
"target_id": note_id,
"scope": "chunk",
"note_id": owner,
}) })
prev_id = ch.get("neighbors",{}).get("prev") # Nachbarn
next_id = ch.get("neighbors",{}).get("next") nb = ch.get("neighbors") or {}
prev_id = nb.get("prev")
next_id = nb.get("next")
if prev_id: if prev_id:
edges.append({"src_id": ch["id"], "dst_id": prev_id, "edge_type": "next", "scope": "chunk"}) edges.append({
edges.append({"src_id": prev_id, "dst_id": ch["id"], "edge_type": "prev", "scope": "chunk"}) "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: if next_id:
edges.append({"src_id": ch["id"], "dst_id": next_id, "edge_type": "next", "scope": "chunk"}) edges.append({
edges.append({"src_id": next_id, "dst_id": ch["id"], "edge_type": "prev", "scope": "chunk"}) "kind": "next",
"source_id": cid,
# references aus wikilinks (Chunk-Scope) "target_id": next_id,
for ref in ch.get("references", []): "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") tid = ref.get("target_id")
if not tid: continue if not tid:
edges.append({"src_id": ch["id"], "dst_id": tid, "edge_type": "references", "scope": "chunk"}) continue
edges.append({"src_id": tid, "dst_id": ch["id"], "edge_type": "backlink", "scope": "chunk"}) edges.append({
"kind": "references",
"source_id": cid,
"target_id": tid,
"scope": "chunk",
"note_id": owner,
})
# depends_on / assigned_to (Note-Scope, aus Frontmatter) # Note-Scope: backlink (immer); references (optional)
for dep in note_meta.get("depends_on", []) or []: unique_refs = list(dict.fromkeys(note_level_refs or []))
edges.append({"src_id": note_meta["id"], "dst_id": dep, "edge_type": "depends_on", "scope": "note"}) for tid in unique_refs:
for ass in note_meta.get("assigned_to", []) or []: if include_note_scope_refs:
edges.append({"src_id": note_meta["id"], "dst_id": ass, "edge_type": "assigned_to", "scope": "note"}) edges.append({
"kind": "references",
# Note-Level references (optional: falls du im Note-Payload `references` sammelst) "source_id": note_id,
for tid in note_meta.get("references", []) or []: "target_id": tid,
edges.append({"src_id": note_meta["id"], "dst_id": tid, "edge_type": "references", "scope": "note"}) "scope": "note",
edges.append({"src_id": tid, "dst_id": note_meta["id"], "edge_type": "backlink", "scope": "note"}) "note_id": note_id,
})
edges.append({
"kind": "backlink",
"source_id": tid,
"target_id": note_id,
"scope": "note",
"note_id": note_id,
})
# Dedupe # Dedupe
uniq = {} dedup = {}
for e in edges: for e in edges:
k = (e["src_id"], e["edge_type"], e["dst_id"], e.get("scope","note")) k = (e["kind"], e["source_id"], e["target_id"], e.get("scope", ""))
uniq[k] = e dedup[k] = e
return list(uniq.values()) return list(dedup.values())
+145 -114
View File
@@ -1,98 +1,85 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" # Modul: app/core/note_payload.py
Modul: app/core/note_payload.py # Version: 1.7.0
Version: 1.4.0 # Datum: 2025-09-09
Datum: 2025-09-09
Kurzbeschreibung
----------------
Erzeugt den Qdrant-Payload für **Notes**. Neben stabiler Hash-Bildung zur
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).
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)
Beispiele (CLI – Sichtprüfung)
------------------------------
python3 -m app.core.note_payload --from-file ./vault/demo.md --vault-root ./vault --print
"""
from __future__ import annotations from __future__ import annotations
import argparse import argparse
import hashlib import hashlib
import json import json
import os import os
from typing import Any, Dict, Optional from typing import Any, Dict, Optional, Tuple
try: 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 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: def _canon_frontmatter(fm: Dict[str, Any]) -> str:
"""Kanonische, stabile JSON-Serialisierung der Frontmatter für Hashbildung."""
return json.dumps(fm or {}, ensure_ascii=False, separators=(",", ":"), sort_keys=True) return json.dumps(fm or {}, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
def _normalize_body(body: str, mode: str) -> str: def _normalize_body(body: str, mode: str) -> str:
"""Normalisiert den Body für reproduzierbare Hashes (oder nicht)."""
if mode == "none": if mode == "none":
return body if body is not None else "" return body if body is not None else ""
# canonical: \r\n→\n, trailing spaces, mehrfach-blankzeilen trimmen
text = (body or "").replace("\r\n", "\n").replace("\r", "\n") 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")) text = "\n".join(line.rstrip() for line in text.split("\n"))
# keine aggressivere Logik (keine inhaltliche Änderung)
return text return text
def compute_hash( def _resolve_hash_mode(explicit: Optional[str]) -> str:
*, if explicit:
body: Optional[str], val = explicit.strip().lower()
frontmatter: Optional[Dict[str, Any]], else:
mode: Optional[str] = None, val = (os.environ.get("MINDNET_HASH_MODE")
normalize: Optional[str] = None, or os.environ.get("MINDNET_HASH_COMPARE")
) -> str: or "body").strip().lower()
""" if val in ("full", "fulltext", "body+frontmatter", "bodyplusfrontmatter"):
Berechnet einen Hex-Hash gemäß ``mode`` und ``normalize``. return "full"
if val in ("frontmatter", "fm"):
return "frontmatter"
return "body"
mode: def _read_raw_body_from_file(file_path: Optional[str]) -> Tuple[str, Dict[str, Any]]:
- "body" (Default) if not file_path or not os.path.exists(file_path):
- "frontmatter" return "", {}
- "body+frontmatter" try:
normalize: with open(file_path, "r", encoding="utf-8") as f:
- "canonical" (Default) raw = f.read()
- "none" except Exception:
""" return "", {}
mode = (mode or os.environ.get("MINDNET_HASH_MODE", "body")).strip().lower() m = FRONTMATTER_RE.match(raw)
normalize = (normalize or os.environ.get("MINDNET_HASH_NORMALIZE", "canonical")).strip().lower() fm = {}
if m:
body = _normalize_body(body or "", normalize) fm_txt = m.group(1)
fm_s = _canon_frontmatter(frontmatter or {}) try:
import yaml # lazy
fm = yaml.safe_load(fm_txt) or {}
except Exception:
fm = {}
body = raw[m.end():]
else:
body = raw
return body, fm
def _sha256(s: str) -> str:
h = hashlib.sha256() h = hashlib.sha256()
if mode == "frontmatter": h.update(s.encode("utf-8"))
h.update(fm_s.encode("utf-8"))
elif mode == "body+frontmatter":
h.update(body.encode("utf-8"))
h.update(b"\n--FM--\n")
h.update(fm_s.encode("utf-8"))
else: # body
h.update(body.encode("utf-8"))
return h.hexdigest() return h.hexdigest()
def _hash_for(mode: str, *, body: str, fm: Dict[str, Any], normalize: str) -> str:
body_n = _normalize_body(body or "", normalize)
fm_s = _canon_frontmatter(fm or {})
if mode == "frontmatter":
return _sha256(fm_s)
if mode == "full":
return _sha256(body_n + "\n--FM--\n" + fm_s)
# default: body
return _sha256(body_n)
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
# Kernfunktion # Kernfunktion
@@ -104,51 +91,84 @@ def make_note_payload(
*, *,
hash_mode: Optional[str] = None, hash_mode: Optional[str] = None,
hash_normalize: Optional[str] = None, hash_normalize: Optional[str] = None,
hash_source: Optional[str] = None,
file_path: Optional[str] = None,
) -> Dict[str, Any]: ) -> Dict[str, Any]:
""" """
Erzeugt den Payload für eine geparste Note. Liefert den Note-Payload inkl. Mehrfach-Hashes.
- Es werden IMMER die drei Hashes für (body|frontmatter|full) unter
Parameters 'parsed:canonical' erzeugt (Schlüssel: z. B. 'body:parsed:canonical').
---------- - Zusätzlich werden – falls die aktuelle Konfig (source/normalize) davon
parsed : Any abweicht – die drei Hashes unter den entsprechenden Schlüsseln erzeugt,
Objekt mit Attributen/Keys ``frontmatter``, ``body``, ``path``. z. B. 'frontmatter:raw:none'.
vault_root : Optional[str] - 'hash_fulltext' und 'hash_signature' repräsentieren den *aktuellen* Modus.
Vault-Wurzel (für Pfad-Relativierung). Wenn ``None``, wird ``path`` unverändert übernommen.
hash_mode : Optional[str]
"body" | "frontmatter" | "body+frontmatter" (überschreibt ENV).
hash_normalize : Optional[str]
"canonical" | "none" (überschreibt ENV).
Returns
-------
Dict[str, Any]
Qdrant-Payload für die Notes-Collection.
""" """
# "Duck typing": dict oder Objekt akzeptieren # dict oder Objekt akzeptieren
fm = ( if isinstance(parsed, dict):
getattr(parsed, "frontmatter", None) fm = parsed.get("frontmatter") or {}
or getattr(parsed, "fm", None) body_parsed = parsed.get("body") or ""
or getattr(parsed, "front_matter", None) path = parsed.get("path") or ""
or (parsed.get("frontmatter") if isinstance(parsed, dict) else {}) else:
) or {} fm = getattr(parsed, "frontmatter", {}) or {}
body = getattr(parsed, "body", None) or (parsed.get("body") if isinstance(parsed, dict) else "") or "" body_parsed = getattr(parsed, "body", "") or ""
path = getattr(parsed, "path", None) or (parsed.get("path") if isinstance(parsed, dict) else "") or "" path = getattr(parsed, "path", "") or ""
# Hash gem. Modus bilden # Zielpfad relativieren
hash_fulltext = compute_hash(body=body, frontmatter=fm, mode=hash_mode, normalize=hash_normalize)
# Pfad relativieren
rel_path = path rel_path = path
try: try:
if vault_root: if vault_root:
rel = os.path.relpath(path, vault_root) rel = os.path.relpath(path, vault_root)
rel = rel.replace("\\", "/").lstrip("/") # normalisieren rel = rel.replace("\\", "/").lstrip("/")
rel_path = rel rel_path = rel
except Exception: except Exception:
pass # Pfad nicht kritisch für Hash/ID pass
# Optionale Note-Level-Wikilinks (Fallback, wenn Chunks nicht geliefert werden) # Konfiguration auflösen
note_level_refs = list(dict.fromkeys(extract_wikilinks(body))) if body else [] mode_resolved = _resolve_hash_mode(hash_mode) # body|frontmatter|full
src = (hash_source or os.environ.get("MINDNET_HASH_SOURCE", "parsed")).strip().lower() # parsed|raw
norm = (hash_normalize or os.environ.get("MINDNET_HASH_NORMALIZE", "canonical")).strip().lower() # canonical|none
# Body-Quelle laden
raw_body, raw_fm = ("", {})
if src == "raw":
raw_body, raw_fm = _read_raw_body_from_file(file_path or path)
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
body_for_hash = raw_body
else:
body_for_hash = body_parsed
# --- 1) Standard-Tripel (parsed:canonical) immer erzeugen ---
std_src = "parsed"
std_norm = "canonical"
std_hashes: Dict[str, str] = {}
for m in ("body", "frontmatter", "full"):
std_hashes[f"{m}:{std_src}:{std_norm}"] = _hash_for(
m, body=body_parsed, fm=fm, normalize=std_norm
)
# Convenience-Felder (für Tools)
hash_body = std_hashes["body:parsed:canonical"]
hash_frontmatter = std_hashes["frontmatter:parsed:canonical"]
hash_full = std_hashes["full:parsed:canonical"]
# --- 2) Hashes für die *aktuelle* Konfiguration (falls abweichend) ---
cur_hashes: Dict[str, str] = {}
if not (src == std_src and norm == std_norm):
for m in ("body", "frontmatter", "full"):
cur_hashes[f"{m}:{src}:{norm}"] = _hash_for(
m, body=body_for_hash, fm=fm, normalize=norm
)
# --- 3) Aktueller Modus für Backwards-Compat Felder ---
current_hash = _hash_for(mode_resolved, body=body_for_hash, fm=fm, normalize=norm)
hash_signature = f"{mode_resolved}:{src}:{norm}:{current_hash}"
# Wikilinks (Note-Ebene)
refs = list(dict.fromkeys(extract_wikilinks(body_parsed))) if body_parsed else []
payload: Dict[str, Any] = { payload: Dict[str, Any] = {
"note_id": fm.get("id") or fm.get("note_id"), "note_id": fm.get("id") or fm.get("note_id"),
@@ -159,40 +179,51 @@ def make_note_payload(
"updated": fm.get("updated"), "updated": fm.get("updated"),
"path": rel_path or fm.get("path"), "path": rel_path or fm.get("path"),
"tags": fm.get("tags"), "tags": fm.get("tags"),
"hash_fulltext": hash_fulltext, # Volltext für verlustfreien Export
# Volltext persistieren (verlustfreie Rekonstruktion) "fulltext": body_parsed,
"fulltext": body, # Backwards-Compat:
# Fallback-Refs auf Note-Ebene "hash_fulltext": current_hash,
"references": note_level_refs, "hash_signature": hash_signature,
# Option C: Mehrfach-Hashes
"hashes": {**std_hashes, **cur_hashes},
"hash_body": hash_body,
"hash_frontmatter": hash_frontmatter,
"hash_full": hash_full,
# Fallback-Refs
"references": refs,
} }
for k in ("area", "project", "source", "lang", "slug"): for k in ("area", "project", "source", "lang", "slug", "aliases"):
if k in fm: if k in fm:
payload[k] = fm[k] payload[k] = fm[k]
return payload return payload
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
# CLI – Sichtprüfung # CLI – Sichtprüfung
# --------------------------------------------------------------------------- # ---------------------------------------------------------------------------
def _cli() -> None: def _cli() -> None:
ap = argparse.ArgumentParser(description="Note-Payload aus Markdown erzeugen und anzeigen") ap = argparse.ArgumentParser(description="Note-Payload aus Markdown erzeugen und anzeigen")
ap.add_argument("--from-file", dest="src", required=True, help="Pfad zur Markdown-Datei") ap.add_argument("--from-file", dest="src", required=True)
ap.add_argument("--vault-root", dest="vault_root", default=None, help="Vault-Wurzel zur Pfad-Relativierung") ap.add_argument("--vault-root", dest="vault_root", default=None)
ap.add_argument("--print", dest="do_print", action="store_true", help="Payload auf stdout ausgeben") ap.add_argument("--print", dest="do_print", action="store_true")
ap.add_argument("--hash-mode", choices=["body", "frontmatter", "body+frontmatter"], default=None) ap.add_argument("--hash-mode", choices=["body", "frontmatter", "full"], default=None)
ap.add_argument("--hash-normalize", choices=["canonical", "none"], 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() args = ap.parse_args()
parsed = read_markdown(args.src) parsed = read_markdown(args.src)
payload = make_note_payload(parsed, vault_root=args.vault_root, payload = make_note_payload(
hash_mode=args.hash_mode, hash_normalize=args.hash_normalize) parsed,
vault_root=args.vault_root,
hash_mode=args.hash_mode,
hash_normalize=args.hash_normalize,
hash_source=args.hash_source,
file_path=args.src,
)
if args.do_print: if args.do_print:
print(json.dumps(payload, ensure_ascii=False, indent=2)) print(json.dumps(payload, ensure_ascii=False, indent=2))
if __name__ == "__main__": # pragma: no cover if __name__ == "__main__": # pragma: no cover
_cli() _cli()
+244 -45
View File
@@ -1,67 +1,266 @@
from __future__ import annotations #!/usr/bin/env python3
from dataclasses import dataclass # -*- coding: utf-8 -*-
import re """
import os Modul: app/core/parser.py
import unicodedata Version: 1.7.1 (fault-tolerant, API-kompatibel)
import yaml Datum: 2025-10-01
from typing import Tuple, Dict
FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n?", re.DOTALL) # YAML-Frontmatter am Anfang Zweck
-----
Fehlertolerantes Einlesen von Markdown-Dateien mit YAML-Frontmatter.
Kompatibel zur bisherigen Parser-API, aber robust gegenüber Nicht-UTF-8-Dateien:
- Versucht nacheinander: utf-8 → utf-8-sig → cp1252 → latin-1.
- Bei Fallback wird ein JSON-Warnhinweis auf stdout ausgegeben; der Import bricht NICHT ab.
- YAML-Frontmatter wird mit '---' am Anfang und '---' als Abschluss erkannt.
- extract_wikilinks() normalisiert [[id#anchor|label]] → 'id'.
Öffentliche API (kompatibel):
- class ParsedNote(frontmatter: dict, body: str, path: str)
- read_markdown(path) -> ParsedNote | None
- normalize_frontmatter(fm) -> dict
- validate_required_frontmatter(fm, required: tuple[str,...]=("id","title")) -> None
- extract_wikilinks(text) -> list[str]
- FRONTMATTER_RE (Kompatibilitäts-Konstante; Regex für '---'-Zeilen)
Beispiele
---------
from app.core.parser import read_markdown, normalize_frontmatter, validate_required_frontmatter
parsed = read_markdown("./vault/30_projects/project-demo.md")
fm = normalize_frontmatter(parsed.frontmatter)
validate_required_frontmatter(fm)
body = parsed.body
from app.core.parser import extract_wikilinks
links = extract_wikilinks(body)
Abhängigkeiten
--------------
- PyYAML (yaml)
Lizenz: MIT (projektintern)
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Dict, Optional, Tuple, Iterable, List
import io
import json
import os
import re
try:
import yaml # PyYAML
except Exception as e: # pragma: no cover
yaml = None # Fehler wird zur Laufzeit geworfen, falls wirklich benötigt
# ---------------------------------------------------------------------
# Datamodell
# ---------------------------------------------------------------------
@dataclass @dataclass
class ParsedNote: class ParsedNote:
frontmatter: Dict frontmatter: Dict[str, Any]
body: str body: str
path: str path: str
def _strip_bom(text: str) -> str:
return text.lstrip("\ufeff")
def _normalize_text(t: str) -> str: # ---------------------------------------------------------------------
# Unicode-NFKC + vereinheitlichte Zeilenenden + Trim # Frontmatter-Erkennung
t = unicodedata.normalize("NFKC", t) # ---------------------------------------------------------------------
t = t.replace("\r\n", "\n").replace("\r", "\n")
return t
def read_markdown(path: str) -> ParsedNote: # Öffentliche Kompatibilitäts-Konstante: frühere Skripte importieren FRONTMATTER_RE
with open(path, "r", encoding="utf-8") as f: FRONTMATTER_RE = re.compile(r"^\s*---\s*$") # <— public
raw = _strip_bom(f.read()) # Zusätzlich interner Alias (falls jemand ihn referenziert)
raw = _normalize_text(raw) FRONTMATTER_END = FRONTMATTER_RE # <— public alias
m = FRONTMATTER_RE.match(raw) # interne Namen bleiben bestehen
front, body = {}, raw _FRONTMATTER_HEAD = FRONTMATTER_RE
if m: _FRONTMATTER_END = FRONTMATTER_RE
yaml_block = m.group(1)
body = raw[m.end():]
def _split_frontmatter(text: str) -> Tuple[Dict[str, Any], str]:
"""
Zerlegt Text in (frontmatter: dict, body: str).
Erkennt Frontmatter nur, wenn die erste Zeile '---' ist und später ein zweites '---' folgt.
YAML-Fehler im Frontmatter führen NICHT zum Abbruch: es wird dann ein leeres dict benutzt.
"""
lines = text.splitlines(True) # keep line endings
if not lines:
return {}, ""
if not _FRONTMATTER_HEAD.match(lines[0]):
# kein Frontmatter-Header → gesamter Text ist Body
return {}, text
end_idx = None
# Suche nach nächstem '---' (max. 2000 Zeilen als Sicherheitslimit)
for i in range(1, min(len(lines), 2000)):
if _FRONTMATTER_END.match(lines[i]):
end_idx = i
break
if end_idx is None:
# unvollständiger Frontmatter-Block → behandle alles als Body
return {}, text
fm_raw = "".join(lines[1:end_idx])
body = "".join(lines[end_idx + 1:])
data: Dict[str, Any] = {}
if yaml is None:
raise RuntimeError("PyYAML ist nicht installiert (pip install pyyaml).")
try:
loaded = yaml.safe_load(fm_raw) or {}
if isinstance(loaded, dict):
data = loaded
else:
data = {}
except Exception as e:
# YAML-Fehler nicht fatal machen
print(json.dumps({"warn": "frontmatter_yaml_parse_failed", "error": str(e)}))
data = {}
# optionales kosmetisches Trim: eine führende Leerzeile im Body entfernen
if body.startswith("\n"):
body = body[1:]
return data, body
# ---------------------------------------------------------------------
# Robustes Lesen mit Encoding-Fallback
# ---------------------------------------------------------------------
_FALLBACK_ENCODINGS: Tuple[str, ...] = ("utf-8", "utf-8-sig", "cp1252", "latin-1")
def _read_text_with_fallback(path: str) -> Tuple[str, str, bool]:
"""
Liest Datei mit mehreren Decodierungsversuchen.
Rückgabe: (text, used_encoding, had_fallback)
- had_fallback=True, falls NICHT 'utf-8' verwendet wurde (oder 'utf-8-sig').
"""
last_err: Optional[str] = None
for enc in _FALLBACK_ENCODINGS:
try: try:
front = yaml.safe_load(yaml_block) or {} with io.open(path, "r", encoding=enc, errors="strict") as f:
if not isinstance(front, dict): text = f.read()
raise ValueError("Frontmatter must be a mapping") # 'utf-8-sig' zählt hier als Fallback (weil BOM), aber ist unproblematisch
except yaml.YAMLError as e: return text, enc, (enc != "utf-8")
raise ValueError(f"Invalid YAML frontmatter in {path}: {e}") from e except UnicodeDecodeError as e:
last_err = f"{type(e).__name__}: {e}"
continue
return ParsedNote(frontmatter=front, body=body, path=path) # Letzter, extrem defensiver Fallback: Bytes → UTF-8 mit REPLACE (keine Exception)
with open(path, "rb") as fb:
raw = fb.read()
text = raw.decode("utf-8", errors="replace")
print(json.dumps({
"path": path,
"warn": "encoding_fallback_exhausted",
"info": last_err or "unknown"
}, ensure_ascii=False))
return text, "utf-8(replace)", True
RE_WIKILINK = re.compile(r"\[\[([^\]\|#]+)(?:#[^\]]+)?(?:\|[^\]]+)?\]\]") # [[id]] | [[id#anchor]] | [[id|label]]
def extract_wikilinks(text: str) -> list[str]: # ---------------------------------------------------------------------
return list({m.group(1).strip() for m in RE_WIKILINK.finditer(text)}) # Öffentliche API
# ---------------------------------------------------------------------
def validate_required_frontmatter(fm: dict, required=("title","id","type","status","created")): def read_markdown(path: str) -> Optional[ParsedNote]:
missing = [k for k in required if k not in fm or fm[k] in (None, "")] """
Liest eine Markdown-Datei fehlertolerant:
- Erlaubt verschiedene Encodings (UTF-8 bevorzugt, cp1252/latin-1 als Fallback).
- Schlägt NICHT mit UnicodeDecodeError fehl.
- Gibt ParsedNote(frontmatter, body, path) zurück oder None, falls die Datei nicht existiert.
Bei Decoding-Fallback wird ein JSON-Warnhinweis geloggt:
{"path": "...", "warn": "encoding_fallback_used", "used": "cp1252"}
"""
if not os.path.exists(path):
return None
text, enc, had_fb = _read_text_with_fallback(path)
if had_fb:
print(json.dumps({"path": path, "warn": "encoding_fallback_used", "used": enc}, ensure_ascii=False))
fm, body = _split_frontmatter(text)
return ParsedNote(frontmatter=fm or {}, body=body or "", path=path)
def validate_required_frontmatter(fm: Dict[str, Any],
required: Tuple[str, ...] = ("id", "title")) -> None:
"""
Prüft, ob alle Pflichtfelder vorhanden sind.
Default-kompatibel: ('id', 'title'), kann aber vom Aufrufer erweitert werden, z. B.:
validate_required_frontmatter(fm, required=("id","title","type","status","created"))
Hebt ValueError, falls Felder fehlen oder leer sind.
"""
if fm is None:
fm = {}
missing = []
for k in required:
v = fm.get(k)
if v is None:
missing.append(k)
elif isinstance(v, str) and not v.strip():
missing.append(k)
if missing: if missing:
raise ValueError(f"Missing required frontmatter fields: {', '.join(missing)}") raise ValueError(f"Missing required frontmatter fields: {', '.join(missing)}")
# einfache Plausibilitäten # Plausibilitäten: 'tags' sollte eine Liste sein, wenn vorhanden
if not isinstance(fm.get("tags", []), (list, tuple)): if "tags" in fm and fm["tags"] not in (None, "") and not isinstance(fm["tags"], (list, tuple)):
if "tags" in fm and fm["tags"] not in (None, ""): raise ValueError("frontmatter 'tags' must be a list of strings")
raise ValueError("tags must be a list of strings")
def normalize_frontmatter(fm: dict) -> dict:
# kleinere Normalisierungen ohne die Semantik zu verändern def normalize_frontmatter(fm: Dict[str, Any]) -> Dict[str, Any]:
out = dict(fm) """
if "tags" in out and isinstance(out["tags"], list): Sanfte Normalisierung ohne Semantikänderung:
out["tags"] = [str(t).strip() for t in out["tags"]] - 'tags' → Liste von Strings (Trim)
- 'embedding_exclude' → bool
- andere Felder unverändert
"""
out = dict(fm or {})
if "tags" in out:
if isinstance(out["tags"], str):
out["tags"] = [out["tags"].strip()] if out["tags"].strip() else []
elif isinstance(out["tags"], list):
out["tags"] = [str(t).strip() for t in out["tags"] if t is not None]
else:
out["tags"] = [str(out["tags"]).strip()] if out["tags"] not in (None, "") else []
if "embedding_exclude" in out: if "embedding_exclude" in out:
out["embedding_exclude"] = bool(out["embedding_exclude"]) out["embedding_exclude"] = bool(out["embedding_exclude"])
return out return out
# ------------------------------ Wikilinks ---------------------------- #
# Basismuster für [[...]]; die Normalisierung (id vor '#', vor '|') macht extract_wikilinks
_WIKILINK_RE = re.compile(r"\[\[([^\]]+)\]\]")
def extract_wikilinks(text: str) -> List[str]:
"""
Extrahiert Wikilinks wie [[id]], [[id#anchor]], [[id|label]], [[id#anchor|label]].
Rückgabe sind NUR die Ziel-IDs (ohne Anchor/Label), führend/folgend getrimmt.
Keine aggressive Slug-Normalisierung (die kann später im Resolver erfolgen).
"""
if not text:
return []
out: List[str] = []
for m in _WIKILINK_RE.finditer(text):
raw = (m.group(1) or "").strip()
if not raw:
continue
# Split an Pipe (Label) → links vor '|'
if "|" in raw:
raw = raw.split("|", 1)[0].strip()
# Split an Anchor
if "#" in raw:
raw = raw.split("#", 1)[0].strip()
if raw:
out.append(raw)
return out
+31 -59
View File
@@ -2,30 +2,16 @@
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """
Name: app/core/qdrant.py Name: app/core/qdrant.py
Version: v1.3.1 (2025-09-05) Version: v1.4.0 (2025-09-09)
Kurzbeschreibung: Kurzbeschreibung:
Qdrant-Client & Collection-Setup für mindnet. Qdrant-Client & Collection-Setup für mindnet.
- Stellt sicher, dass {prefix}_notes / {prefix}_chunks / {prefix}_edges existieren. - Stellt sicher, dass {prefix}_notes / {prefix}_chunks / {prefix}_edges existieren.
- Edges-Collection nutzt 1D Dummy-Vektor (Workaround für Python-Client). - Edges-Collection nutzt 1D Dummy-Vektor.
- **Nicht-destruktiv per Default**: ensure_collections(..., destructive=False). - NEW: ensure_payload_indexes(...) legt sinnvolle Payload-Indizes an.
- **Abwärtskompatibel**: collection_names(prefix) wieder verfügbar.
Aufruf/Verwendung: Aufruf:
from app.core.qdrant import QdrantConfig, get_client, ensure_collections, collection_names from app.core.qdrant import QdrantConfig, get_client, ensure_collections, ensure_payload_indexes
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}
""" """
from __future__ import annotations from __future__ import annotations
import os import os
@@ -36,10 +22,6 @@ from qdrant_client import QdrantClient
from qdrant_client.http import models as rest from qdrant_client.http import models as rest
# -------------------------------
# Konfiguration
# -------------------------------
@dataclass @dataclass
class QdrantConfig: class QdrantConfig:
url: str url: str
@@ -60,18 +42,10 @@ class QdrantConfig:
return QdrantConfig(url=url, api_key=api_key, prefix=prefix, dim=dim) return QdrantConfig(url=url, api_key=api_key, prefix=prefix, dim=dim)
# -------------------------------
# Client
# -------------------------------
def get_client(cfg: QdrantConfig) -> QdrantClient: def get_client(cfg: QdrantConfig) -> QdrantClient:
return QdrantClient(url=cfg.url, api_key=cfg.api_key) return QdrantClient(url=cfg.url, api_key=cfg.api_key)
# -------------------------------
# Collection-Erzeuger (Hilfsfunktionen)
# -------------------------------
def _create_notes(client: QdrantClient, name: str, dim: int) -> None: def _create_notes(client: QdrantClient, name: str, dim: int) -> None:
if not client.collection_exists(name): if not client.collection_exists(name):
client.create_collection( 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: 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" notes = f"{prefix}_notes"
chunks = f"{prefix}_chunks" chunks = f"{prefix}_chunks"
edges = f"{prefix}_edges" edges = f"{prefix}_edges"
@@ -112,41 +77,48 @@ def ensure_collections(client: QdrantClient, prefix: str, dim: int, destructive:
_create_chunks(client, chunks, dim) _create_chunks(client, chunks, dim)
if client.collection_exists(edges): if client.collection_exists(edges):
# Prüfen, ob die Edges-Collection bereits eine Vektorkonfig hat
try: try:
info = client.get_collection(edges) info = client.get_collection(edges)
vectors_cfg = getattr(getattr(info.result, "config", None), "params", None) vectors_cfg = getattr(getattr(info.result, "config", None), "params", None)
has_vectors = getattr(vectors_cfg, "vectors", None) is not None has_vectors = getattr(vectors_cfg, "vectors", None) is not None
except Exception: except Exception:
# konservativ: nichts anfassen, um Datenverlust zu vermeiden
has_vectors = True has_vectors = True
if not has_vectors: if not has_vectors:
if destructive: if destructive:
client.delete_collection(edges) client.delete_collection(edges)
_create_edges(client, edges) _create_edges(client, edges)
else: else:
print( print(f"[ensure_collections] WARN: '{edges}' ohne VectorConfig; destructive=False.", flush=True)
f"[ensure_collections] WARN: '{edges}' ohne VectorConfig gefunden; "
f"keine destruktive Änderung (destructive=False).",
flush=True,
)
else: else:
_create_edges(client, edges) _create_edges(client, edges)
def collection_names(prefix: str) -> Tuple[str, str, str]: 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") return (f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges")
def wipe_collections(client: QdrantClient, prefix: str) -> None: # -------------------------------
""" # NEW: Payload-Indexing
Löscht alle drei Collections – nur verwenden, wenn bewusst ein Clean-Rebuild gewünscht ist. # -------------------------------
"""
for name in collection_names(prefix): def _safe_create_index(client: QdrantClient, col: str, field: str, schema: rest.PayloadSchemaType):
if client.collection_exists(name): try:
client.delete_collection(name) 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)
+172
View File
@@ -0,0 +1,172 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Modul: app/graph/service.py
Version: 0.1.0
Datum: 2025-09-10
Zweck
-----
Leichtgewichtiger Graph-Layer über Qdrant:
- get_note(note_id)
- get_chunks(note_id)
- neighbors(source_id, kinds=[...], scope=['note','chunk'], depth=1)
- walk_bfs(source_id, kinds, max_depth)
- context_for_note(note_id, max_neighbors): heuristische Kontextsammlung
Hinweise
--------
- Nutzt die bestehenden Collections <prefix>_notes/_chunks/_edges.
- Edges werden über Payload-Felder (`kind`, `source_id`, `target_id`) abgefragt.
"""
from __future__ import annotations
from typing import List, Dict, Any, Optional, Iterable, Set, Tuple
from qdrant_client.http import models as rest
from app.core.qdrant import QdrantConfig, get_client
def _cols(prefix: str):
return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges"
class GraphService:
def __init__(self, cfg: Optional[QdrantConfig] = None, prefix: Optional[str] = None):
self.cfg = cfg or QdrantConfig.from_env()
if prefix:
self.cfg.prefix = prefix
self.client = get_client(self.cfg)
self.notes_col, self.chunks_col, self.edges_col = _cols(self.cfg.prefix)
# ------------------------ fetch helpers ------------------------
def _scroll(self, col: str, flt: Optional[rest.Filter] = None, limit: int = 256):
out = []
nextp = None
while True:
pts, nextp = self.client.scroll(
collection_name=col,
with_payload=True,
with_vectors=False,
limit=limit,
offset=nextp,
scroll_filter=flt,
)
if not pts:
break
out.extend(pts)
if nextp is None:
break
return out
# ------------------------ public API ---------------------------
def get_note(self, note_id: str) -> Optional[Dict[str, Any]]:
f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
pts, _ = self.client.scroll(self.notes_col, with_payload=True, with_vectors=False, limit=1, scroll_filter=f)
return (pts[0].payload or None) if pts else None
def get_chunks(self, note_id: str) -> List[Dict[str, Any]]:
f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
pts = self._scroll(self.chunks_col, f)
# Sortierung analog Export
def key(pl):
p = pl.payload or {}
s = p.get("seq") or 0
ci = p.get("chunk_index") or 0
n = 0
cid = p.get("chunk_id") or ""
if isinstance(cid, str) and "#" in cid:
try:
n = int(cid.rsplit("#", 1)[-1])
except Exception:
n = 0
return (int(s), int(ci), n)
pts_sorted = sorted(pts, key=key)
return [p.payload or {} for p in pts_sorted]
def neighbors(self, source_id: str, kinds: Optional[Iterable[str]] = None,
scope: Optional[Iterable[str]] = None, depth: int = 1) -> Dict[str, List[Dict[str, Any]]]:
"""
Liefert eingehende & ausgehende Nachbarn (nur nach kind gefiltert).
depth==1: direkte Kanten.
"""
kinds = list(kinds) if kinds else None
must = [rest.FieldCondition(key="source_id", match=rest.MatchValue(value=source_id))]
if kinds:
must.append(rest.FieldCondition(key="kind", match=rest.MatchAny(any=kinds)))
f = rest.Filter(must=must)
edges = self._scroll(self.edges_col, f)
out = {"out": [], "in": []}
for e in edges:
out["out"].append(e.payload or {})
# Inverse Richtung (eingehend)
must_in = [rest.FieldCondition(key="target_id", match=rest.MatchValue(value=source_id))]
if kinds:
must_in.append(rest.FieldCondition(key="kind", match=rest.MatchAny(any=kinds)))
f_in = rest.Filter(must=must_in)
edges_in = self._scroll(self.edges_col, f_in)
for e in edges_in:
out["in"].append(e.payload or {})
return out
def walk_bfs(self, source_id: str, kinds: Iterable[str], max_depth: int = 2) -> Set[str]:
visited: Set[str] = {source_id}
frontier: Set[str] = {source_id}
kinds = list(kinds)
for _ in range(max_depth):
nxt: Set[str] = set()
for s in frontier:
neigh = self.neighbors(s, kinds=kinds)
for e in neigh["out"]:
t = e.get("target_id")
if isinstance(t, str) and t not in visited:
visited.add(t)
nxt.add(t)
frontier = nxt
if not frontier:
break
return visited
def context_for_note(self, note_id: str, kinds: Iterable[str] = ("references","backlink"), max_neighbors: int = 12) -> Dict[str, Any]:
"""
Heuristischer Kontext: eigene Chunks + Nachbarn nach Kantenarten, dedupliziert.
"""
note = self.get_note(note_id) or {}
chunks = self.get_chunks(note_id)
neigh = self.neighbors(note_id, kinds=list(kinds))
targets = []
for e in neigh["out"]:
t = e.get("target_id")
if isinstance(t, str):
targets.append(t)
for e in neigh["in"]:
s = e.get("source_id")
if isinstance(s, str):
targets.append(s)
# de-dupe
seen = set()
uniq = []
for t in targets:
if t not in seen:
seen.add(t)
uniq.append(t)
uniq = uniq[:max_neighbors]
neighbor_notes = [self.get_note(t) for t in uniq]
return {
"note": note,
"chunks": chunks,
"neighbors": [n for n in neighbor_notes if n],
"edges_out": neigh["out"],
"edges_in": neigh["in"],
}
# Optional: Mini-CLI
if __name__ == "__main__": # pragma: no cover
import argparse, json
ap = argparse.ArgumentParser()
ap.add_argument("--prefix", help="Collection-Prefix (überschreibt ENV)")
ap.add_argument("--note-id", required=True)
ap.add_argument("--neighbors", action="store_true", help="Nur Nachbarn anzeigen")
args = ap.parse_args()
svc = GraphService(prefix=args.prefix)
if args.neighbors:
out = svc.neighbors(args.note_id, kinds=["references","backlink","prev","next","belongs_to"])
else:
out = svc.context_for_note(args.note_id)
print(json.dumps(out, ensure_ascii=False, indent=2))
+234 -75
View File
@@ -1,19 +1,42 @@
# 📘 Mindnet Skript-Handbuch # 📘 Mindnet Skript-Handbuch (aktualisiert)
Dieses Handbuch dokumentiert die implementierten Skripte für das Projekt **mindnet Wissensnetzwerk**. Dieses Handbuch dokumentiert die Skripte und Tests für das Projekt **mindnet Wissensnetzwerk**.
Es beschreibt Zweck, Parameter und typische Aufrufe. Alle Beispiele sind geprüft und lauffähig. Es beschreibt Zweck, Parameter, typische Aufrufe sowie aktuelle Verhaltensweisen (Hash-Modi, Parser-Robustheit, `window`/`text`-Trennung in Chunks, Export-Fixes).
Alle Beispiele sind so formatiert, dass sie direkt kopierbar sind. **Code/CLI-Beispiele sind eingerückt**, damit die Markdown-Darstellung nicht abbricht.
Alle Skripte liegen in `~/mindnet/scripts/`.
Ausführung erfolgt **im aktivierten venv**:
cd ~/mindnet
source .venv/bin/activate
--- ---
## 1. Vault anlegen (für Tests) ## 0) Umgebung & Konfiguration
### `make_test_vault.py` **Wichtige ENV-Variablen**
- `QDRANT_URL` – z. B. `http://localhost:6333`
- `QDRANT_API_KEY` – API-Key (falls aktiviert)
- `COLLECTION_PREFIX` – Prefix der drei Collections, Standard: `mindnet` → `mindnet_notes`, `mindnet_chunks`, `mindnet_edges`
- `VECTOR_DIM` – Embedding-Dimension (Chunks), Standard: `384`
**Hash-Vergleich & Änderungs­erkennung**
- `MINDNET_HASH_COMPARE` – steuert, **welcher Anteil** für „changed“ verglichen wird
Werte: `Body` (Standard), `Frontmatter`, `Full`
- `MINDNET_HASH_SOURCE` – Quelle: `parsed` (Standard), `raw`, `file`
- `MINDNET_HASH_NORMALIZE` – Normalisierung: `canonical` (Standard) oder `none`
**Beispiel (nur Body berücksichtigen, kanonisch, geparst):**
export MINDNET_HASH_COMPARE=Body
export MINDNET_HASH_SOURCE=parsed
export MINDNET_HASH_NORMALIZE=canonical
source .venv/bin/activate
**Baseline-Signaturen (mehrere Modi):**
Der Importer kann **Signaturen aller Modi** (Body/Frontmatter/Full) vorhalten, damit spätere Moduswechsel deterministisch sind (keine „Mass-Changes“). Siehe `--baseline-modes` unter **Importer**.
---
## 1) Vault anlegen (für Tests)
### `scripts/make_test_vault.py`
**Zweck:** **Zweck:**
Erstellt einen kleinen, nachvollziehbaren Test-Vault mit Markdown-Dateien. Erstellt einen kleinen, nachvollziehbaren Test-Vault mit Markdown-Dateien.
@@ -22,17 +45,17 @@ Szenarien: offene Links, nachträgliche Anlage fehlender Notes, geänderte Chunk
**Parameter:** **Parameter:**
- `--out PATH` : Zielverzeichnis (Default: `./test_vault`) - `--out PATH` : Zielverzeichnis (Default: `./test_vault`)
- `--force` : Existierenden Ordner löschen und neu anlegen - `--force` : Existierenden Ordner löschen und neu anlegen
- `--with-missing` : Optional – auch die `missing-note` gleich anlegen - `--with-missing` : Optional – auch die `missing-note` gleich anlegen
**Hinweise für Tests** **Hinweise für Tests**
1) Erster Import (dry-run oder --apply): Es gibt einen „leeren“ Link [[missing-note]]. 1. Erster Import (dry-run oder `--apply`): Es gibt einen „leeren“ Link `[[missing-note]]`.
2) Lege danach eine Datei für „missing-note“ an (mit gleicher ID im YAML) und importiere erneut: 2. Lege danach eine Datei für „missing-note“ an (mit gleicher `id` im YAML) und importiere erneut:
-> Erwartung: Edges für ehemals leeren Link werden korrekt nachgezogen (references + backlink). → Erwartung: Edges für ehemals leeren Link werden korrekt nachgezogen (`references` + `backlink`).
3) Ändere den Body von exp-one.md so, dass andere Chunk-Grenzen entstehen und importiere erneut: 3. Ändere den Body von `exp-one.md` so, dass andere Chunk-Grenzen entstehen und importiere erneut:
-> Erwartung: Chunks/Edges/Note werden für betroffene Noten aktualisiert. → Erwartung: Chunks/Edges/Note werden für betroffene Noten aktualisiert.
Kompatibel mit: **Kompatibilität:**
- note.schema.json: 'created'/'updated' müssen strings sein. (Wichtig!) - `note.schema.json`: `created`/`updated` sind Strings.
**Beispiele:** **Beispiele:**
@@ -41,41 +64,60 @@ Kompatibel mit:
--- ---
## 2. Import in Qdrant ## 2) Import in Qdrant
### `import_markdown.py` ### `scripts/import_markdown.py`
**Zweck:** **Zweck:**
Importiert Notes/Chunks/Edges aus einem Vault nach Qdrant. Importiert Notes/Chunks/Edges aus einem Vault nach Qdrant.
- prüft Frontmatter - validiert Frontmatter
- chunked Inhalte + Embeddings - chunked Inhalte + Embeddings
- erzeugt Edges (`references`, `references_at`, `backlink`) - erzeugt Edges (`references`, `references_at`, `backlink`, `next`, `prev`, `belongs_to`)
- erkennt geänderte Dateien automatisch - erkennt geänderte Dateien **modusgesteuert** (Body/Frontmatter/Full)
- optional: Purge der alten Chunks/Edges pro Note - optional: Purge der alten Chunks/Edges pro Note
**Parameter:** **Parameter:**
- `--vault PATH` : (Pflicht) Vault-Verzeichnis - `--vault PATH` : (Pflicht) Vault-Verzeichnis
- `--apply` : Änderungen wirklich durchführen (sonst Dry-Run) - `--apply` : Änderungen wirklich durchführen (ohne: Dry-Run)
- `--purge-before-upsert` : Vor Upsert alte Chunks/Edges **nur der geänderten Notes** löschen - `--purge-before-upsert` : Vor Upsert alte Chunks/Edges **nur der geänderten Notes** löschen
- `--note-id ID` : Nur eine bestimmte Note importieren - `--prefix STR` : überschreibt `COLLECTION_PREFIX`
- `--note-id ID` : nur eine bestimmte Note importieren
- `--note-scope-refs` : zusätzlich **note-weite** `references` erzeugen (nicht nur chunk-weise)
- `--baseline-modes` : berechne & speichere Hash-Signaturen für **alle** Modi (`Body`, `Frontmatter`, `Full`) als Baseline
**Erwartetes Verhalten:**
- Unveränderte Notes → `"changed": false`, Entscheidung: `apply-skip-unchanged` (bei `--apply`)
- Geänderte Notes → `"changed": true` (abhängig von `MINDNET_HASH_COMPARE`)
- Idempotenz: mehrfacher Lauf ohne Änderungen erzeugt **keine** neuen Punkte
- Baseline: Bei `--baseline-modes` erscheinen Felder wie `hash_signature`, `hash_fulltext`, ggf. `hash_frontmatter` und `needs_baseline_for_mode: false` bei Folgeläufen.
**Beispiele:** **Beispiele:**
python3 -m scripts.import_markdown --vault ./vault # Dry-Run (zeigt Änderungen, schreibt NICHT)
python3 -m scripts.import_markdown --vault ./vault --apply python3 -m scripts.import_markdown --vault ./vault --prefix mindnet
python3 -m scripts.import_markdown --vault ./vault --apply --purge-before-upsert
# Apply + gezielte Vorreinigung pro geänderter Note
python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply --purge-before-upsert
# Baseline-Signaturen aller Modi vorhalten
python3 -m scripts.import_markdown --vault ./vault --apply --baseline-modes
**Hash-Modi in der Praxis:**
- `MINDNET_HASH_COMPARE=Body` → Änderungen im Body werden erkannt; reine Frontmatter-Änderungen bleiben **ohne Effekt**.
- `MINDNET_HASH_COMPARE=Frontmatter` → nur Frontmatter maßgeblich.
- `MINDNET_HASH_COMPARE=Full` → beide Anteile zählen.
--- ---
## 3. Konsistenzprüfungen ## 3) Konsistenzprüfungen
### `audit_vault_vs_qdrant.py` ### `scripts/audit_vault_vs_qdrant.py`
**Zweck:** **Zweck:**
Vergleicht Vault-Inhalte mit Qdrant. Vergleicht Vault-Inhalte mit Qdrant.
- Zählt Notes/Chunks/Edges - Zählt Notes/Chunks/Edges
- Verifiziert Anzahl Wikilinks vs. Edges - Verifiziert Anzahl Wikilinks vs. Edges
- Meldet Mismatches pro Note - Meldet Deltas (z. B. `references` im Vault vs. in Qdrant)
**Parameter:** **Parameter:**
- `--vault PATH` : Vault-Verzeichnis - `--vault PATH` : Vault-Verzeichnis
@@ -85,15 +127,13 @@ Vergleicht Vault-Inhalte mit Qdrant.
python3 -m scripts.audit_vault_vs_qdrant --vault ./vault --prefix mindnet python3 -m scripts.audit_vault_vs_qdrant --vault ./vault --prefix mindnet
--- ### `scripts/validate_edges.py`
### `validate_edges.py`
**Zweck:** **Zweck:**
Prüft die Edges-Collection in Qdrant. Prüft die Edges-Collection in Qdrant.
- Zählt Edges pro Typ - Zählt Edges pro Typ (`references`, `references_at`, `backlink`, `next`, `prev`, `belongs_to`)
- Kontrolliert Invarianten (z. B. jede Reference hat Backlink) - Kontrolliert Invarianten (z. B. jede `references` hat einen `backlink`)
- Listet unresolved Edges auf - Listet `unresolved` Edges auf
**Parameter:** **Parameter:**
- `--prefix STR` : Prefix für Qdrant-Collections - `--prefix STR` : Prefix für Qdrant-Collections
@@ -105,35 +145,69 @@ Prüft die Edges-Collection in Qdrant.
--- ---
## 4. Qdrant zurücksetzen ## 4) Export Qdrant → Markdown (Vault)
### `reset_qdrant.py` ### `scripts/export_markdown.py`
**Zweck:** **Zweck:**
Setzt die Qdrant-Collections zurück. Exportiert Notes + rekonstruierten Body in einen Zielordner.
- „wipe“: löscht Collections komplett (inkl. Schema) - Pfade werden **relativ** aus `note.payload.path` abgeleitet (führende `/` entfernt, Backslashes → Slashes; Unicode-NFC empfohlen)
- „truncate“: löscht nur Inhalte, behält Collections - **Body-Rekonstruktion** priorisiert:
1. `fulltext` (falls in Note-Payload vorhanden)
2. sonst **Chunks**: Sortierung `seq` → `chunk_index` → Nummer in `chunk_id`; **nur `text`** (Overlap bereits entfernt)
- `--prefix` (CLI) wird unterstützt (oder ENV `COLLECTION_PREFIX`)
**Parameter:** **Parameter:**
- `--mode {wipe,truncate}` : Aktion - `--out PATH` : Ziel-Root (muss existieren)
- `--prefix STR` : Prefix der Collections (Default: `mindnet`) - `--overwrite` : vorhandene Dateien überschreiben
- `--yes` : Automatische Bestätigung - `--note-id ID` : nur eine bestimmte Note exportieren
- `--dry-run` : Nur anzeigen, nicht ausführen - `--prefix STR` : überschreibt `COLLECTION_PREFIX`
- `--include-edges {none,footer,yaml}` *(optional, falls aktiviert)*: Edges als YAML-Liste im Frontmatter oder im Footer beilegen
**Beispiele:** **Beispiele:**
export COLLECTION_PREFIX="mindnet"
python3 -m scripts.export_markdown --out ./_exportVault
# Nur eine bestimmte Note:
python3 -m scripts.export_markdown --out ./_exportVault --note-id 20250821-architektur-ki-trainerassistent-761cfe
# Existierende Dateien überschreiben:
python3 -m scripts.export_markdown --out ./_exportVault --overwrite
---
## 5) Qdrant zurücksetzen
### `scripts/reset_qdrant.py`
**Zweck:**
Setzt die Qdrant-Collections zurück.
- `wipe`: löscht Collections komplett (inkl. Schema)
- `truncate`: löscht nur Inhalte, behält Collections
- `truncate-edges`: löscht nur Punkte in `*_edges`
**Parameter:**
- `--mode {wipe,truncate,truncate-edges}`
- `--prefix STR` : Prefix der Collections (Default: `mindnet`)
- `--yes` : Automatische Bestätigung
- `--dry-run` : Nur anzeigen, nicht ausführen
**Beispiele:**
python3 -m scripts.reset_qdrant --mode truncate-edges --prefix mindnet
python3 -m scripts.reset_qdrant --mode truncate --prefix mindnet --yes python3 -m scripts.reset_qdrant --mode truncate --prefix mindnet --yes
python3 -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes python3 -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes
--- ---
## 5. Diagnose ## 6) Diagnose & Tools
### `diagnose_changed.py` ### `scripts/diagnose_changed.py`
**Zweck:** **Zweck:**
Prüft, ob die Datei-Hashes (`sha256`) mit den gespeicherten `hash_fulltext` in Qdrant übereinstimmen. Prüft, ob Datei-Hashes (`sha256`) mit gespeicherten `hash_*` in Qdrant übereinstimmen.
Hilft, wenn der Importer zu viele Dateien als „changed“ erkennt. Hilft, wenn der Importer zu viele Dateien als „changed“ erkennt oder Moduswechsel geplant sind.
**Parameter:** **Parameter:**
- `--vault PATH` : Vault-Verzeichnis - `--vault PATH` : Vault-Verzeichnis
@@ -145,14 +219,11 @@ Hilft, wenn der Importer zu viele Dateien als „changed“ erkennt.
python3 -m scripts.diagnose_changed --vault ./vault --prefix mindnet --all python3 -m scripts.diagnose_changed --vault ./vault --prefix mindnet --all
--- ### `scripts/resolve_unresolved_references.py`
## 6. Unresolved Links nachträglich auflösen
### `resolve_unresolved_references.py`
**Zweck:** **Zweck:**
Prüft offene Wikilinks (`status=unresolved`) und fügt Edges nach, wenn inzwischen passende Notizen existieren. Prüft offene Wikilinks (`status=unresolved`) und fügt Edges nach, wenn inzwischen passende Notizen existieren.
Ersetzt `unresolved` durch gültige `references`/`backlink`.
**Parameter:** **Parameter:**
- `--prefix STR` : Prefix für Qdrant-Collections - `--prefix STR` : Prefix für Qdrant-Collections
@@ -165,26 +236,114 @@ Prüft offene Wikilinks (`status=unresolved`) und fügt Edges nach, wenn inzwisc
--- ---
# ✅ Typische Workflows ## 7) Parser-Verhalten (robust & abwärtskompatibel)
### A) Vault neu importieren - Der Parser liest Markdown **fehlertolerant** (UTF-8 mit Fallbacks), extrahiert YAML-Frontmatter und Body.
- Keine harten Abhängigkeiten von alten Regex-Symbolen (`FRONTMATTER_RE` entfällt zugunsten interner Marker).
- `read_markdown(path)` gibt `(frontmatter_dict, body_str)` zurück.
- **Sonderfälle aus Fremd-Tools** (z. B. Silverbullet-Dateien wie `CONFIG.md`, `index.md`) werden **nicht importiert**, sofern sie nicht zum Vault gehören.
---
## 8) Chunk-Payload (Fenster vs. Kern)
- **`window`** = kontextualisierter Fenster-Text (mit linkem Overlap)
- **`text`** = **Kerntext** ohne das vom vorherigen Chunk übernommene Overlap
- Felder: `start`, `end`, `overlap_left`, `overlap_right`, `chunk_index`, `seq`, `path`, `section_title`, `section_path`, `token_count` (falls vorhanden)
- **Fallback (synthetisch):** Falls der Chunker **keinen** Overlap-Fenstertext liefert, erzeugt die Payload-Schicht Fenster mit typgerechtem Overlap aus `chunk_config.get_sizes(type)['overlap']` (unterer Wert).
- **Edges** werden aus `window` abgeleitet (um Links an Chunk-Grenzen nicht zu verlieren); der **Export** rekonstruiert den Body aus `text` (Overlap-frei).
---
## 9) Edge-Modell & IDs
- Collections:
`*_notes` (optional Vektor / Nullvektor), `*_chunks` (384-d Embeddings), `*_edges` (1-d Dummy-Vektor)
- **Deterministische IDs** (UUIDv5 / stabile Keys):
- `note_id` stabil aus Frontmatter/Slug
- `chunk_id` i. d. R. `note_id#<n>`
- `edge_id` stabil aus `(kind, source_id, target_id, seq)`
- Kantenarten: `references`, `references_at`, `backlink`, `next`, `prev`, `belongs_to`
- `unresolved` wird gekennzeichnet und kann per Resolver später aufgelöst werden.
---
## 10) Tests & Qualitätssicherung
**Tests unter `tests/`**
- `check_chunks_window_vs_text.py` – vergleicht je Chunk `window` vs. `text`, schätzt Overlap
- `compare_vaults.py` – rekursiver Vault-Vergleich (Body/Frontmatter/All, Key: auto/id/title/filename), Unicode-NFC-robust
- `verify_chunks_integrity.py` – prüft, ob Rekonstruktion aus Chunks (`text`) zu `fulltext` bzw. zum Vault-Body passt
- `list_md_seen_by_importer.py` – zeigt, welche `.md` der Importer sieht (inkl. Gründe/Filter)
- `inspect_one_note.py` – Parser-Diagnose für eine konkrete Datei
- `run_e2e_roundtrip.sh` – End-to-End: Reset → Import → Audit → (optional) Hash-Reporter → Export → Vergleich
**Typische Aufrufe:**
# Overlap-Qualität (Fenster vs. Kern)
python3 tests/check_chunks_window_vs_text.py --prefix "$COLLECTION_PREFIX"
# Roundtrip-Vergleich (rekursiv)
python3 tests/compare_vaults.py --src ./vault --dst ./_exportVault --focus body
# Chunks-Rekonstruktion (gegen Vault-Body)
python3 tests/verify_chunks_integrity.py --prefix "$COLLECTION_PREFIX" --vault ./vault
---
## 11) Typische Workflows
**A) Clean-Start mit Test-Vault**
python3 -m scripts.make_test_vault --out ./test_vault --force
python3 -m scripts.reset_qdrant --mode truncate --prefix mindnet --yes python3 -m scripts.reset_qdrant --mode truncate --prefix mindnet --yes
python3 -m scripts.import_markdown --vault ./vault --apply python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet
python3 -m scripts.audit_vault_vs_qdrant --vault ./vault --prefix mindnet python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet --apply --purge-before-upsert
python3 -m scripts.audit_vault_vs_qdrant --vault ./test_vault --prefix mindnet
python3 -m scripts.validate_edges --prefix mindnet --details
export COLLECTION_PREFIX="mindnet"
python3 -m scripts.export_markdown --out ./_exportVault
### B) Änderungen einspielen (mit Purge für geänderte Notes) **B) Änderungs-Propagation & Idempotenz**
python3 -m scripts.import_markdown --vault ./vault --apply --purge-before-upsert python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet
python3 -m scripts.audit_vault_vs_qdrant --vault ./vault --prefix mindnet python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet --apply --purge-before-upsert
python3 -m scripts.audit_vault_vs_qdrant --vault ./test_vault --prefix mindnet
python3 -m scripts.validate_edges --prefix mindnet --details
python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet
### C) Unresolved Links nachziehen **C) Unresolved Links lösen**
python3 -m scripts.import_markdown --vault ./test_vault --apply --prefix mindnet
python3 -m scripts.resolve_unresolved_references --prefix mindnet --apply python3 -m scripts.resolve_unresolved_references --prefix mindnet --apply
python3 -m scripts.validate_edges --prefix mindnet --details python3 -m scripts.validate_edges --prefix mindnet --details
### D) Test-Vault Szenario durchspielen **D) Export & Roundtrip (Produkt-Vault)**
python3 -m scripts.make_test_vault --out ./test_vault --force export COLLECTION_PREFIX="mindnet"
python3 -m scripts.import_markdown --vault ./test_vault --apply python3 -m scripts.import_markdown --vault ./vault --apply --purge-before-upsert --prefix "$COLLECTION_PREFIX"
python3 -m scripts.audit_vault_vs_qdrant --vault ./test_vault --prefix mindnet python3 -m scripts.export_markdown --out ./_exportVault --prefix "$COLLECTION_PREFIX"
python3 tests/compare_vaults.py --src ./vault --dst ./_exportVault --focus body
---
## 12) Troubleshooting (kurz)
- **Importer markiert alle als changed (Moduswechsel):**
→ `--baseline-modes` einmalig laufen lassen; sicherstellen: `MINDNET_HASH_COMPARE` passt zum Ziel.
- **Edges verschwinden / nur 1 Edge sichtbar:**
→ `app/core/qdrant_points.py` muss Edge-Payload normalisieren (Schema Alt/Neu) und `edge_id` eindeutig bilden.
- **Export ohne Body / falsches Zielverzeichnis:**
→ Exporter nutzt relativierte Pfade und rekonstruiert Body aus `fulltext` oder Chunks (`text`). ENV/CLI `--prefix` beachten.
- **Parser-Fehler (UTF-8):**
→ Neuer Parser arbeitet mit Fallbacks; mit `tests/inspect_one_note.py` prüfen, was ankommt.
- **„Fehlende“ Dateien im Vergleich:**
→ Prüfe, ob Dateien **wirklich zum Vault gehören** (z. B. Silverbullet-Artefakte `CONFIG.md`, `index.md` ausblenden).
---
## 13) Hinweise zu Silverbullet-Dateien
- Dateien wie `CONFIG.md` oder `index.md`, die **nicht** zum inhaltlichen Vault gehören, werden **nicht importiert** und erscheinen daher nicht im Export-Roundtrip.
- Diese Dateien bitte vom produktiven Vault trennen oder im Vergleich (`tests/compare_vaults.py
+106 -116
View File
@@ -13,74 +13,67 @@ Entwickle eine robuste, parser-freundliche **Chunking-Strategie** für Markdown-
--- ---
## 2) Annahmen aus `knowledge_design.md` ## 2) Annahmen aus `knowledge_design.md`
- **Stabile IDs** & Dateinamen-Schema (z. B. `YYYYMMDD-HHMM-type-slug` bzw. `type-slug`). - **IDs**: deterministische, stabile `id` pro Note (Slug / semantischer Identifier), ggf. `aliases`.
- **Pflichtfelder** in YAML: `title`, `id`, `type`, `status`, `created`, `tags` (empfohlene Felder ggf. mehr). - **Dateinamen**: entweder `YYYY-MM-DD_title.md` oder `slug.md`; Pfade sind **relativ** zum Vault.
- **Abschnitts-Konventionen** je `type` (z. B. `## Zusammenfassung`, `## Kontext` …) → ideale **Chunk-Grenzen**. - **Frontmatter-Pflichtfelder**: `id`, `title`, `type`, `created`, `updated` (Details in `knowledge_design.md`).
- **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`). - **Backlink-/Link-Regeln**: Wikilinks `[[id]]` im Body; am Ende optional redaktionelle Sektion „Mögliche Verbindungen“ (erzeugt **keine** Kanten).
--- ---
## 3) Chunking-Prinzipien ## 3) Chunking-Prinzipien
1. **Frontmatter extrahieren** → als strukturiertes `metadata` (nicht in `text` des Chunks). - **Semantische Schnitte**: Chunks enden an Absätzen, Überschriften, Listenpunkten, Codeblöcken, Zitaten.
2. **Markdown AST** (oder strukturierter Parser) nutzen: - **Frontmatter**: YAML **nicht** embedden; stattdessen komplett im Note-Payload speichern.
- Primäre Grenzen: **Überschriftenebene H2/H3** (H1 = Dokumenttitel). - **Verlustfreiheit**:
- Sekundär: **Absätze**, **nummerierte/unnummerierte Listen** als atomare Einheiten, **Codeblöcke** als zusammenhängender Block (nicht splitten). - Note-Payload: `fulltext` (gesamter Body).
3. **Längensteuerung**: Semantik vor harter Länge. Wenn Abschnitt > Zielgröße, **weich segmentieren** entlang von Absätzen/Listenpunkten. - Chunk-Payload: `text` (Originalchunk).
4. **Referenz-Extraktion**: `[[Wikilinks]]` + Markdown-Links → `references`. Backlinks werden downstream generiert. Damit kann der Export den Body **verlustfrei** rekonstruieren (erst `fulltext`, sonst Chunks).
5. **Kontext-Overlap**: Chunks erhalten **Überlappung** über Satz-/Absatzgrenzen, um Kohärenz beim Retrieval zu erhöhen.
--- ---
## 4) Optimale Chunkgrößen & Overlaps ## 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 ## 4.1 Overlap-Regeln
- Overlap **nie mitten im Satz** beenden → mindestens **ein kompletter Satz** wandert in den nächsten Chunk. - Overlap betrifft **nur den Body**; die YAML-Frontmatter bleibt **außerhalb**.
- An **Absatzgrenzen** ausrichten, wenn möglich. - Keine Overlaps, die Codeblöcke oder Tabellen „aufreißen“. Falls nötig: Chunk-Grenze an Blockgrenze ziehen.
- Bei **Listen** ggf. den vorherigen Punkt als Overlap mitführen (falls < 50 Tokens). - Bei reinen Listen: zusammenhängende Bullets gruppieren, ggf. kleinere Overlaps.
- 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).
--- ---
## 5) Semantische Regeln je Strukturelement ## 5) Semantische Regeln je Strukturelement
- **Überschriften (H2/H3)**: new chunk start; speichere `section_path` (z. B. `/Kontext/Beobachtung`). - **Überschriften**: vorzugsweise an H2/H3 trennen; H1 meist Dokumenttitel → Teil der Frontmatter.
- **Absätze**: Primäre Untereinheiten; wenn Zusammenfassung + Beispiel direkt folgen, zusammen lassen. - **Absätze**: primäre Trennkandidaten.
- **Listen**: Jeder **Listeneintrag** bleibt zusammen mit seinem einleitenden Satz (falls vorhanden). Große Listen → in **logische Blöcke** (5–8 Items) splitten. - **Listen**: zusammenhängende Gruppe als ein Chunk, wenn sie einen semantischen Block bilden.
- **Codeblöcke**: Nicht splitten; ggf. separater Chunk, **aber** im Retrieval **downweighten** (optional). - **Codeblöcke**: niemals splitten; Code bleibt in einem Chunk.
- **Zitate/Blockquotes**: zusammenhalten; Quelle im `references_meta` anreichern (falls Link vorhanden). - **Zitate**: ab 2+ Zeilen als eigener Chunk.
- **Tabellen**: als ein Chunk; zusätzlich **Plain-Text-Extrakt** (Header + 1–2 Zeilen) in `summary` für Retriever, falls Modelle Tabellen schlechter verarbeiten. - **Bilder/Anhänge**: Referenzen im Text belassen; Pfade relativ halten.
--- ---
## 6) Normalisierung & Preprocessing ## 6) Normalisierung & Preprocessing
- **Nicht embedden:** YAML-Frontmatter (aber spezifische Felder als `metadata.*` mitschreiben: `type`, `tags`, `area`, `project`, `priority`, `people`, `aliases`). - **Zeilenenden**: `\r\n` → `\n`, trailing spaces trimmen (nur für Hashing, nicht für Anzeige).
- **Bereinigen:** führende/trailing Spaces, Mehrfach-Leerzeilen → 1; Unicode-NFKC; Zeilenenden normalisieren. - **Whitespace**: mehrfach-Blankzeilen reduzieren (optional, Hash-Modus beachten).
- **Bewahren:** Markdown-Semantik (Überschriften-Hashes, Listenpräfixe, Codefences) **im Text beibehalten**, damit RAG-Antworten sauber zitieren können. - **Links**: `[[Titel|id]]` zu `(display="Titel", target_id="id")` normalisieren.
- **Sprachhinweis:** `lang` heuristisch bestimmen (DE/EN/…); in `metadata.lang` ablegen → später für sprachspezifische Embeddings nützlich. - **Pfade**: `path` im Payload **zwingend relativ** (Backslashes → Slashes).
- **Stop-Abschnitte:** „Mögliche Verbindungen“ am Ende **separat** chunken (nur Links), um Link-Graph sauber zu extrahieren.
--- ---
## 7) Edge-Modell (Graph) ## 7) Edge-Modell (Graph)
- **Chunk → Note:** `belongs_to(note_id)` (obligatorisch). - **Chunk → Note:** `belongs_to(note_id)` (obligatorisch; Edge-Payload enthält zusätzlich `note_id` als Owner-Note).
- **Chunk → Chunk (gleiche Note):** `prev`, `next` (lineare Leserichtung). - **Chunk → Chunk (gleiche Note):** `prev`, `next` (symmetrisch für lineare Navigation; beide Richtungen werden erzeugt).
- **Note/Chunk → Note:** `references(target_id)` aus `[[Wikilinks]]` & Markdown-Links; optional `related` (schwach). - **Chunk → Note:** `references(target_id)` aus `[[Wikilinks]]` oder Markdown-Links im Chunk-Text (Standard; *Chunk-Scope*).
- **Backlink:** systemisch generiert: inverse Kante `backlink`. - **Note → Note:** `backlink(target_id)` automatisch generiert, dedupliziert pro Note (*Note-Scope*).
- **Sektionen:** `has_section(note_id, section_path)` (optional, für Navigations-UI). - **Optional:** `references:note` (Note-Scope-References) per Flag/ENV aktivierbar; **Default = aus**, um Doppelzählungen zu vermeiden.
- **Task-Spezialfälle:** `depends_on`, `assigned_to(person-id)` bleiben **Note-Level** (nicht Chunk-Level). - **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", "project": "project-mindnet",
"tags": ["area/mindnet","type/thought","topic/yaml"], "tags": ["area/mindnet","type/thought","topic/yaml"],
"chunk_index": 2, "chunk_index": 2,
"char_start": 1240, "char_start": 1024,
"char_end": 2012, "char_end": 1789,
"token_count": 305,
"section_title": "Begründung / Details", "section_title": "Begründung / Details",
"section_path": "/Begründung / Details", "section_path": "Begründung / Details",
"lang": "de", "neighbors": {"prev": "…#c01", "next": "…#c03"},
"wikilinks": ["concept-vektorsuche-qdrant","source-obsidian-properties"], "wikilinks": ["concept-yaml-styleguide"],
"external_links": [], "references": [{"kind":"wikilink", "target_id":"concept-yaml-styleguide"}],
"references": [ "text": "… ursprünglicher Chunk-Text …"
{"target_id": "concept-vektorsuche-qdrant", "kind": "wikilink"}
],
"neighbors": {"prev": "#c01", "next": "#c03"},
"created_at": "2025-09-02T18:35:00+02:00"
} }
} }
**Collection-Einstellungen (Empfehlung)** **Point (Note)**
- `distance`: `Cosine` (gemischte Textlängen)
- `vectors`: 384–1024 Dim (abh. Embedding-Modell) {
- `hnsw_ef_construct`: 128–256; `m`: 16–32 (Workload-abhängig) "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) blocks = group_blocks(sec, keep_code=True, keep_lists=True)
for group in soft_wrap(blocks, target_tokens=target_size(meta["type"]), for group in soft_wrap(blocks, target_tokens=target_size(meta["type"]),
max_tokens=max_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 = apply_overlap(raw_chunks, overlap_tokens=overlap(meta["type"]))
chunks = trim_whitespace(chunks) chunks = normalize_chunks(chunks) # trim, fix code fences, etc.
# link extraction # IDs & Nachbarn
for i, ch in enumerate(chunks): for i, ch in enumerate(chunks, start=1):
ch.payload.update({ ch.id = f"{meta['id']}#c{i:02d}"
"wikilinks": extract_wikilinks(ch.text), ch.index = i
"external_links": extract_md_links(ch.text), ch.neighbors_prev = chunks[i-2].id if i > 1 else None
"references": [{"target_id": t, "kind": "wikilink"} for t in extract_wikilinks(ch.text)], ch.neighbors_next = chunks[i].id if i < len(chunks) else None
"neighbors": {"prev": f"#c{i-1}" if i>0 else None,
"next": f"#c{i+1}" if i<len(chunks)-1 else None}
})
# attach metadata # Wikilinks je Chunk
for idx, ch in enumerate(chunks): for ch in chunks:
ch.id = f'{meta["id"]}#c{idx:02d}' ch.wikilinks = extract_wikilinks(ch.text)
ch.payload |= minimal_payload_from_meta(meta, file_path, idx, ch)
return chunks 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) ## 10) Einbettung (Embeddings)
- **Standard:** nur `chunk.text` embedden (ohne YAML), **aber**: - Modell: MiniLM/all-MiniLM-L6-v2 (384d) oder E5 (besseres Retrieval, ggf. multilingual).
- `aliases`, `title` können als **synthetischer Kontext** *vorangestellt* werden (konkateniert, durch Trennzeichen), falls Recall für Synonyme wichtig ist. - **Note-Embeddings** optional (Zentroid der Chunks).
- **Mehrsprachigkeit:** pro Chunk die Sprache detektieren; ggf. **mehrsprachige Modelle**/Pipelines verwenden. - **Hashing für Change-Detection** (Importer):
- **Code-Gewichtung:** optional zweite Vektor-Spur für Code (separate Collection) falls viel Technik. - `MINDNET_HASH_MODE = body|frontmatter|body+frontmatter` (Default: `body`)
- `MINDNET_HASH_NORMALIZE = canonical|none` (Default: `canonical`)
--- ---
## 11) Qualitätssicherung ## 11) Qualitätssicherung
- **Unit-Tests**: Gold-Notes mit erwarteten Section-Splits und Link-Graph. - **Zähler**: `notes/chunks/edges` je Lauf prüfen.
- **Metrics**: Retrieval-Eval (nDCG@k, Recall@k) auf internen QA-Fragen. - **Edge-Invarianten**:
- **Linting**: Pre-commit prüft Pflichtfelder & Link-Integrität (IDs, Dateinamen, Wikilinks). - `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 ## 12) Deliverables
1. **Python-Modul** `mindnet_chunker/` (Parser, Chunker, Link-Extractor, Qdrant-Client). - Code: Parser, Chunker, Importer, Exporter, Edges.
2. **CLI** `mindnet-chunk` (stdin→stdout, oder Datei→NDJSON). - Schemas: `note.schema.json`, Payload-Layouts.
3. **Docs**: README mit Schema & Beispielen; Tests + Fixtures. - Tests: Mini-Vault (`scripts/make_test_vault.py`), Audit/Validate.
--- ---
## 13) Prompt für neues Chatfenster (kopieren & einfügen) ## 13) Prompt für neues Chatfenster (kopieren & einfügen)
*(Unverändert)*
**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.
+186 -373
View File
@@ -1,436 +1,249 @@
--- # mindnet – Knowledge Design
title: "mindnet – Knowledge Design" **Version:** 1.4.0 (aktualisiert 2025-10-06)
id: "design-knowledge-architecture"
type: "guide"
status: "active"
version: "1.2.0"
created: 2025-09-02
updated: 2025-09-02
tags: ["type/guide","area/mindnet","topic/obsidian","topic/knowledge-architecture"]
owner: "Ich"
---
# mindnet – Knowledge Design ## 1. Gesamtziel und Systemverständnis
## 1. Gesamtziel, Anspruch & Nutzen **mindnet** ist ein lokales Wissensnetzwerk, das alle meine Notizen, Projekte, Gedanken, Erfahrungen und Pläne als Markdown-Dateien speichert, automatisch importiert, semantisch in **Chunks** zerlegt und als **Graph-Struktur in Qdrant** ablegt.
Es ist die Grundlage für ein agentenfähiges, lokal betriebenes LLM-System, das meine Daten verknüpft, abfragt und erweitert.
**Ziel:** **Zentrale Ziele**
*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. - Vollständige Repräsentation persönlichen Wissens in strukturierter, maschinenlesbarer Form
- Reproduzierbare Verarbeitung: Import → Chunking → Embedding → Edges → Graph
- Verlustfreie Roundtrip-Fähigkeit (Import ⇄ Export)
- Erweiterbarkeit für Agenten, RAG-Retriever und semantische Suche
**Anspruch an die Struktur:** **Prinzipien**
- **Stabil**: robuste IDs, deterministische Dateinamen, konsistente Feldnamen - **Deterministisch:** IDs, Hashes und Edges wiederholbar
- **Atomar**: ein Kerninhalt pro Datei (keine Sammelcontainer) - **Portabel:** Markdown + YAML
- **Erweiterbar**: neue Typen (z. B. `milestone`, `manifesto`) jederzeit möglich - **Robust:** fehlertoleranter Parser
- **Portabel**: reines Markdown + YAML → funktioniert in Obsidian, Git und Parsern - **Idempotent:** keine Duplikate bei Re-Import
- **Vernetzbar**: systematische Links/Backlinks erzeugen ein sinnvoll navigierbares Netz - **Erweiterbar:** neue Typen und Edge-Arten ohne Migration
- **Parser-freundlich**: wiederkehrende Abschnittsüberschriften; Felder/Enums klar definiert
**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
--- ---
## 2. YAML-Frontmatter-Schema ## 2. YAML-Frontmatter-Schema
> **Pflichtfelder:** `title`, `id`, `type`, `status`, `created`, `tags` | Feld | Typ | Beschreibung |
> **Empfohlen:** `updated`, `area`, `project`, `priority`, `aliases` (u. a.) |-------|-----|--------------|
| `title` | string | Menschlich lesbarer Titel |
| `id` | string | Eindeutige Note-ID (Slug) |
| `type` | enum | `concept`, `thought`, `experience`, `task`, `project`, `journal`, `person`, `meeting`, `milestone` |
| `status` | enum | `draft`, `active`, `done`, `archived` |
| `created` | date | ISO-Datum |
| `updated` | date | Letzte Änderung |
| `area` | string | Themen- oder Lebensbereich |
| `project` | string | Zugehöriges Projekt |
| `tags` | list | Strukturierte Tags (`area/…`, `topic/…`) |
| `depends_on` | list | IDs anderer Notizen |
| `assigned_to` | list | Beteiligte Personen |
| `embedding_exclude` | bool | Falls `true`, keine Embeddings |
| `hash_mode` | enum | Hash-Modus beim Import (`body`, `frontmatter`, `full`) |
| `priority` | enum/int | 1–5 oder `low` / `med` / `high` |
| `effort_min`, `due` | int/date | Aufwand / Termin |
| `aliases` | list | Alternative IDs |
| `lang` | string | ISO-Sprachcode |
| `source` | string | Herkunft / Referenzquelle |
### 2.1 Feldübersicht **Pflichtfelder:** `title`, `id`, `type`, `status`, `created`
**Optionale Felder:** alle übrigen
| 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` |
### 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`.
### 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
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`
--- ---
## 3. Dateinamen-Konventionen ## 3. Dateinamen und Ordner
> Keine Sonderzeichen wie `: / \` im Dateinamen. - Format: `YYYY-MM-DD_title.md` oder `slug.md`
- Strukturierte Ordner:
- **Zeitbasierte Notizen (Gedanken, Journal, tagesgebundene Einträge):** - `10_thoughts/`, `20_concepts/`, `30_projects/`, `40_experiences/`, …
`YYYYMMDD-HHMM-<type>-<slug>.md` - Alle Pfade relativ; Unterstriche statt Leerzeichen
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/
--- ---
## 4. Tagging-Regeln & Taxonomie ## 4. Link- und Edge-Design
- **Hierarchische Tags:** **Verlinkungen**
- `area/*` – Lebens-/Arbeitsbereiche: `area/mindnet`, `area/family`, `area/karate`, `area/health`, … - Wikilinks: `[[note-id]]` oder `[[Titel|note-id]]`
- `type/*` – optionaler Spiegel von `type`: `type/thought`, `type/experience`, … - Automatische Edges aus Text und Frontmatter
- `topic/*` – thematische Schwerpunkte: `topic/obsidian`, `topic/yaml`, `topic/qdrant`, `topic/werte`, …
- optional: `place/*`, `person/*`, `level/*` (z. B. `person/rouven`, `person/rohan`) **Edge-Typen in Qdrant**
- **Regeln:**
- Jede Notiz hat **mindestens ein** `area/*`. | Typ | Bedeutung | Quelle | Scope |
- `topic/*` sparsam, aber konsistent; ein Mapping in `_meta/tags.md` pflegen. |------|------------|--------|--------|
- Möglichst **keine** losen Ein-Wort-Tags ohne Präfix (verhindert Wildwuchs). | `belongs_to` | Chunk → Note | intern | chunk |
| `prev` / `next` | Reihenfolge | intern | chunk |
| `references` | explizite Wikilinks | Text | chunk |
| `backlink` | Gegenkante zu `references` | abgeleitet | note |
| `depends_on` | YAML-Abhängigkeiten | YAML | note |
| `assigned_to` | YAML-Zuweisung | YAML | note |
| `unresolved` | Ziel fehlt (Stub) | abgeleitet | chunk |
**Edge-Schlüssel**
- `source_id`, `target_id`, `kind`, `scope`, `note_id`
- Dedup-Schlüssel: Kombination aus `(kind, source_id, target_id, scope)`
--- ---
## 5. Backlink- & Link-Regeln ## 5. Chunking-Modell
- **Wikilinks** verwenden: `[[stabile-id-oder-dateiname]]` **Chunk-Datenstruktur**
- Im **Fließtext** bei erster Nennung verlinken; am **Ende** die Sektion **„Mögliche Verbindungen“** pflegen: | Feld | Beschreibung |
|-------|---------------|
| `note_id` | Zugehörige Note |
| `chunk_index` | Laufende Nummer |
| `text` | Originalabschnitt |
| `window` | Text + Overlap links/rechts |
| `overlap_left` | Länge des linken Overlaps |
| `overlap_right` | Länge des rechten Overlaps |
| `embedding` | 384-dimensionaler Vektor |
| `tokens` | Tokenanzahl (optional) |
## Mögliche Verbindungen **Chunking-Regeln (aus `chunking_strategy.md`)**
- [[concept-persoenliches-leitbild]] - Trennung nach Absätzen, Überschriften, Listen, Tabellen
- [[project-mindnet]] - Token-Zielgröße 350–500 (max 600)
- Overlap: 30–40 % für semantische Kohärenz
- **Linkrichtung:** „aufwärts“ (Detail → Konzept/Leitbild) und „seitwärts“ (verwandte Knoten). - Overlap wird in `window` integriert, sodass `text ≠ window`
- Optional zusätzlich **ID-Relationen** im YAML (`related_ids`) für Parser.
## 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).
- **belongs_to**
Chunk → Note (ein Chunk gehört zu genau einer Note)
- **references**
Note → Note (eine Notiz verweist auf eine andere)
- **backlink**
Automatisch generiert: Gegenkante von `references`
- **depends_on**
Task → Task oder Task → Project (Aufgabe hängt von anderer ab)
- **assigned_to**
Task → Person (eine Aufgabe ist einer Person zugeordnet)
- **discussed_in**
Note/Concept → Meeting (ein Thema wurde in einem Meeting behandelt)
- **authored_by**
Note → Person (z. B. externer Autor oder eigene Urheberschaft)
- **related**
Generische Relation für schwache Assoziationen
--- ---
## 6. Abschnitts-Konventionen im Body ## 6. Hash-Strategie und Änderungsverfolgung
Einheitliche Überschriften erleichtern spätere Parser und Abfragen. **Zweck:** Nur bei realer Inhaltsänderung re-indexieren
- **Gedanke (`thought`)** | Umgebungsvariable | Beschreibung |
`## Zusammenfassung` · `## Begründung / Details` · `## Belege / Quellen` · `## Nächste Schritte` · `## Mögliche Verbindungen` |--------------------|--------------|
- **Erfahrung (`experience`)** | `MINDNET_HASH_COMPARE` | Vergleichsquelle (`Body`, `Full`, `Frontmatter`) |
`## Kontext` · `## Beobachtung` · `## Interpretation` · `## Implikationen` · `## Mögliche Verbindungen` | `MINDNET_HASH_SOURCE` | Rohtext vs. geparst (`raw` / `parsed`) |
- **Aufgabe (`task`)** | `MINDNET_HASH_NORMALIZE` | Normalisierung (`canonical` / `none`) |
`## Checkliste` · `## Notizen` · `## Mögliche Verbindungen`
- **Projekt (`project`)** **Basismodi**
`## Scope` · `## Arbeitspakete` · `## Risiken & Gegenmaßnahmen` · `## Status / Fortschritt` · `## Mögliche Verbindungen` - `body` → Nur Textkörper
- **Journal (`journal`)** - `frontmatter` → Nur Metadaten
`## Tageszusammenfassung` · `## Highlights` · `## Gelernt / Notizen` · `## Mögliche Verbindungen` - `full` → Kombination
- Hash = SHA-256(canonicalized_input)
Bei Änderung: Re-Import, neue Embeddings, Edges werden aktualisiert.
--- ---
## 7. Abbildung persönlicher Inhalte auf Typen ## 7. Qdrant-Speicherstruktur
- **Persönliches Leitbild** → `type: "concept"` (oder optional neuer Typ `manifesto`) | Collection | Inhalt | Primärfelder | Embedding |
Datei: `concept-persoenliches-leitbild.md` (zeitunabhängig) |-------------|---------|---------------|------------|
Verlinkt zu prägenden Erfahrungen und Wendepunkten. | `mindnet_notes` | Notes mit Fulltext & Hash | `note_id` | optional |
- **Erfahrungen, die dich geprägt haben** → `type: "experience"` | `mindnet_chunks` | Chunks mit Text, Window, Embedding | `chunk_id`, `note_id` | 384 d |
Je **eine** prägende Erfahrung pro Datei; klarer Kontext + Interpretation. | `mindnet_edges` | Graphkanten | `edge_id`, `source_id`, `target_id` | — |
- **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). **Upsert-Strategie**
- Idempotente UUIDv5-IDs
- Keine Duplikate durch deterministische Signaturen
- `purge-before-upsert` zur Bereinigung
**Indizes**
- notes: `note_id`, `hash_signature`
- chunks: `note_id`, `chunk_index`
- edges: `(kind, source_id, target_id, scope)`
--- ---
## 8. Beispiel-Notizen ## 8. Fehler-Toleranz und Parser-Robustheit
### 8.1 Gedanke (`thought`) - UTF-8 mit Fallback: ersetzt ungültige Bytes (`errors="replace"`)
--- - Ignoriert Nullbytes, BOM, exotische Zeilenenden
title: "Gedanke: Einheitliche YAML-Standards steigern Recall" - Erkennt defekte oder leere YAML-Header und überspringt sie
id: "20250902-1830-thought-yaml-recall" - Logt Problemfälle (`read_markdown failed`, `make_note_payload returned non-dict`)
type: "thought" - Bei Fehlern: Import → warn → continue
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: []
---
## Zusammenfassung
Konsistente YAML-Felder verbessern Filter, Dataview-Queries und Vektor-Retrieval.
## Begründung / Details
- Parser benötigen stabile Feldnamen (z. B. `type`, `status`).
- Einheitliche Werte erleichtern Dashboards und Automationen.
## Belege / Quellen
- [[source-obsidian-properties]]
- [[concept-vektorsuche-qdrant]]
## Nächste Schritte
- [ ] `tags`-Mapping in `_meta/tags.md` erstellen
- [ ] Beispiel-Queries für Dataview hinterlegen
## Mögliche Verbindungen
- [[project-mindnet]]
- [[20250902-1730-task-yaml-standard-migration]]
### 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"
---
## Kontext
Wiederkehrende Journaleinträge enthalten Rohmaterial für prägende Einsichten.
## Beobachtung
Wird Material regelmäßig zu `experience`-Knoten verdichtet, sind spätere Bezüge einfacher.
## 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: []
---
## 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).
## Mögliche Verbindungen
- [[project-mindnet]]
- [[20250902-1830-thought-yaml-recall]]
--- ---
## 9. Schrittweise Migration bestehender freier Notizen ## 9. Tests & Validierung
**Phase A – Triage (schnell)** **Integrationstests**
1. Sichtung & **Typ** bestimmen (`type`). - Roundtrip: Import → Export → Compare (`compare_vaults.py`)
2. **Minimal-YAML** einfügen (`title`, `id`, `type`, `status=draft`, `created≈Dateidatum`, `tags`). - Chunk-Integrität: `verify_chunks_integrity.py`
3. **Dateiname** grob anpassen (Schema + Slug). - Hash-Audit: `hash_reporter.py`
- Window-Vergleich: `check_chunks_window_vs_text.py`
**Phase B – Strukturieren (fokussiert)** **Erwartete Ergebnisse**
1. **Abschnitte** nach Typ-Template ergänzen. - Alle Notes werden erkannt
2. **Zerlegen**: mehrere Gedanken/Ereignisse → je **eigene Datei**, ursprüngliche Datei wird zum **Index** mit Links. - `window ≠ text` bei > 60 % der Chunks
3. **Verlinken**: relevante `[[Knoten]]` + **„Mögliche Verbindungen“** pflegen. - Roundtrip-Vergleich liefert „OK“
- Edge-Anzahl entspricht Modell (belongs_to = #Chunks, next/prev ≈ #Chunks – 1)
**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.
--- ---
## 10. Dataview-Beispiele (direkt nutzbar) ## 10. Export & Roundtrip-Verhalten
**Offene Aufgaben dieser Woche (nach Priorität):** - `export_markdown.py` erzeugt identische Markdown-Dateien
- Schreibt YAML + Body in korrekter Reihenfolge
TABLE due, priority, effort_min - Roundtrip-Prüfung (`compare_vaults.py`) validiert:
FROM "31_tasks" - vollständigen Body
WHERE type = "task" AND status != "done" - unveränderte Hash-Signatur
AND due >= date(today) - dur(1 week) - gleiche Chunkzahl
AND due <= date(today) + dur(1 week)
SORT priority ASC, due ASC
**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
FROM "10_thoughts"
WHERE type = "thought" AND area = "mindnet"
SORT created DESC
LIMIT 50
**Quellen ohne `source_url` (Pflegebedarf):**
TABLE title, created
FROM "50_sources"
WHERE type = "source" AND (source_url = "" OR !source_url)
--- ---
## 11. Validierung & Pflege ## 11. Graph-Schicht und WP-04-Integration
- **Wöchentlicher Review-Slot (15–30 Min.):** - Qdrant fungiert als Graph-Backend
- Neue Notizen triagieren (`type`, `status`, `area`) - `graph/service.py` (WP-04): stellt API für Mehrhop-Abfragen bereit
- 5 Alt-Notizen migrieren (YAML + Dateiname + Verlinkung) - Unterstützt:
- **Dataview-Checks:** fehlende `source_url`, offene Tasks, aktive Projekte, veraltete `status`. - `expand(note_id, hops=2)`
- **Optional (technisch):** - `resolve_unresolved()`
- **Pre-commit Hook**: prüft Pflichtfelder (`title`, `id`, `type`, `status`, `created`, `tags`) - `neighbors(kind=…)`
- **ID-Generator**: `YYYYMMDD-HHMM-type-slug` bei Neuanlage - Grundlage für spätere **Retriever-Funktionen** (LLM / Agenten)
- **Link-Linter**: prüft tote `[[Links]]`
--- ---
## 12. Versions- & Änderungsrichtlinien ## 12. Agenten- und LLM-Integration
- Dieses Dokument pflegt `version` & `updated`. **Retriever-Pipeline**
- **Breaking Changes** (z. B. Feldumbenennungen) in `_meta/changelog.md` dokumentieren. 1. Suche top-k Chunks (cosine distance)
- **Migrationen** (Tag-Refactorings, Typänderungen) als Skript oder Batch-Checkliste planen. 2. Erweiterung um Edges (`references`, `backlinks`)
3. Kontext-Assembling via `window`-Text
4. Prompt-Generierung
**Agent-Use-Cases**
- Automatisches Tagging (`type`, `status`)
- Vorschläge für neue Edges
- Auflösen von `unresolved`-Referenzen
- Auto-Import externer Quellen (MediaWiki, PDFs, Webseiten)
--- ---
## 13. Typen-Kurzreferenz ## 13. Erweiterbarkeit
- `thought` – Gedanke/These - Neue Edge-Typen: `inspired_by`, `relates_to`, `contradicts`
- `experience` – Beobachtung/Erfahrung mit Interpretation & Implikationen - Neue Note-Typen: `decision`, `resource`, `recommendation`
- `task` – umsetzbare Arbeitseinheit (mit `due`, `effort_min`, `priority`) - Embedding-Engines austauschbar (MiniLM → LaBSE → E5)
- `project` – Container für Ziele/Tasks/Meilensteine - Versionierte Chunking-Strategien (`chunk_config.py`)
- `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
--- ---
## 14 Erweiterungen ## 14. Qualitätssicherung und Best Practices
Zukünftige Typen möglich (z. B. decision, recommendation). - Validierung vor Upsert
- Keine Leer-Chunks
- Vollständige Metadaten in Notes
- Tests in `tests/` automatisch ausführbar (`run_e2e_roundtrip.sh`)
- Ergebnis: „Roundtrip OK“ und `verify_chunks_integrity` = OK
Personalisierung durch zusätzliche Properties (values, goals) ---
## 15. Änderungsverlauf
**v1.4.0 (2025-10-06)**
- Neu: `window` vs `text` Feld in `mindnet_chunks`
- Neu: Hash-Modi (`body`, `frontmatter`, `full`) mit Env-Steuerung
- Neu: Baseline-Modus für Vergleich
- Parser → fehlertolerant (UTF-8 replace)
- Roundtrip-Test vollständig integriert
- Graph-Service und Mehrhop-Abfragen (WP-04-Vorbereitung)
- `purge-before-upsert` und `--note-scope-refs` Parameter ergänzt
**v1.3.0 (2025-09-09)**
- Hash-Normalisierung und Edge-Scope
- Roundtrip-Tests, Agenten-Integration
**v1.2.0 (2025-09-02)**
- Grundstruktur des Knowledge-Designs
---
+79 -27
View File
@@ -2,37 +2,89 @@
"$schema": "https://json-schema.org/draft/2020-12/schema", "$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "mindnet_chunk", "title": "mindnet_chunk",
"type": "object", "type": "object",
"required": ["id", "note_id", "chunk_index", "type", "path", "token_count", "lang"], "description": "Chunk-Payload (Qdrant). Kompatibel mit Alt-Feldern und neuen Feldern für Export/Roundtrip.",
"required": ["id", "note_id", "chunk_index", "path"],
"properties": { "properties": {
"id": {"type": "string"}, "id": { "type": "string" },
"note_id": {"type": "string"}, "scope": { "type": "string", "enum": ["chunk"] },
"note_title": {"type": "string"}, "note_id": { "type": "string" },
"chunk_index": {"type": "integer"}, "note_title": { "type": "string" },
"char_start": {"type": "integer"}, "note_type": { "type": "string" },
"char_end": {"type": "integer"}, "note_status": { "type": "string" },
"token_count": {"type": "integer"}, "type": { "type": "string", "description": "Legacy: früherer Chunk-Typ; kann dem Note-Typ entsprechen" },
"type": {"type": "string"}, "area": { "type": "string" },
"area": {"type": "string"}, "project": { "type": "string" },
"project": {"type": "string"}, "tags": { "type": "array", "items": { "type": "string" } },
"tags": {"type": "array", "items": {"type": "string"}},
"section_title": {"type": "string"}, "note_path": { "type": "string" },
"section_path": {"type": "string"}, "path": { "type": "string" },
"lang": {"type": "string"},
"wikilinks": {"type": "array", "items": {"type": "string"}}, "chunk_index": { "type": "integer" },
"external_links": {"type": "array", "items": {"type": "string"}}, "section_title":{ "type": ["string","null"] },
"section_path": { "type": ["string","null"] },
"char_start": { "type": ["integer","null"] },
"char_end": { "type": ["integer","null"] },
"char_len": { "type": "integer" },
"token_count": { "type": "integer", "description": "Legacy: frühere Token-Zahl" },
"token_est": { "type": "integer", "description": "Neue grobe Token-Schätzung (≈ len(text)/4)" },
"neighbors": {
"type": "object",
"properties": {
"prev": { "type": ["string","null"] },
"next": { "type": ["string","null"] }
},
"additionalProperties": false
},
"text": { "type": "string" },
"text_sha256": { "type": "string", "pattern": "^sha256:[0-9a-fA-F]{64}$" },
"lang": { "type": "string" },
"wikilinks": { "type": "array", "items": { "type": "string" } },
"external_links": {
"type": "array",
"items": {
"anyOf": [
{ "type": "string" },
{
"type": "object",
"properties": {
"href": { "type": "string" },
"label": { "type": ["string","null"] }
},
"required": ["href"],
"additionalProperties": false
}
]
}
},
"references": { "references": {
"type": "array", "type": "array",
"items": {"type": "object", "properties": { "items": {
"target_id": {"type": "string"}, "type": "object",
"kind": {"type": "string"} "properties": {
}, "required": ["target_id", "kind"]} "target_id": { "type": "string" },
"kind": { "type": "string" }
},
"required": ["target_id","kind"],
"additionalProperties": true
}
}, },
"neighbors": {"type": "object", "properties": {
"prev": {"type": ["string","null"]}, "embed_model": { "type": "string" },
"next": {"type": ["string","null"]} "embed_dim": { "type": "integer" },
}}, "embed_version": { "type": "integer" },
"path": {"type": "string"},
"created_at": {"type": "string"} "created_at": { "type": "string" }
}, },
"allOf": [
{ "anyOf": [ { "required": ["token_count"] }, { "required": ["token_est"] } ] },
{ "anyOf": [ { "required": ["type"] }, { "required": ["note_type"] } ] }
],
"additionalProperties": true "additionalProperties": true
} }
+23 -8
View File
@@ -2,15 +2,30 @@
"$schema": "https://json-schema.org/draft/2020-12/schema", "$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "mindnet_edge", "title": "mindnet_edge",
"type": "object", "type": "object",
"required": ["src_id", "dst_id", "edge_type", "scope"], "description": "Edge-Payload (Qdrant). Unterstützt Legacy (edge_type/src_id/dst_id) und neues Schema (kind/source_id/target_id/note_id/status).",
"properties": { "properties": {
"src_id": {"type": "string"}, "scope": { "type": "string", "enum": ["note","chunk"] },
"dst_id": {"type": "string"},
"edge_type": {"type": "string"}, "edge_type": { "type": "string", "description": "Legacy: z. B. references/backlink/belongs_to/prev/next" },
"scope": {"type": "string", "enum": ["note","chunk"]}, "src_id": { "type": "string", "description": "Legacy: source_id" },
"weight": {"type": "number"}, "dst_id": { "type": "string", "description": "Legacy: target_id" },
"meta": {"type": "object"},
"created_at": {"type": "string"} "kind": { "type": "string", "description": "Neu: z. B. references/backlink/belongs_to/prev/next" },
"source_id": { "type": "string" },
"target_id": { "type": "string" },
"note_id": { "type": "string", "description": "Owner-Note für diesen Edge (Filter/Purge)" },
"status": { "type": "string", "description": "optional, z. B. 'unresolved'" },
"weight": { "type": "number" },
"meta": { "type": "object" },
"created_at":{ "type": "string" }
}, },
"anyOf": [
{ "required": ["src_id", "dst_id", "edge_type", "scope"] },
{ "required": ["source_id", "target_id", "kind", "scope"] }
],
"additionalProperties": true "additionalProperties": true
} }
+38 -40
View File
@@ -1,47 +1,45 @@
{ {
"$schema": "https://json-schema.org/draft/2020-12/schema", "$schema": "http://json-schema.org/draft-07/schema#",
"title": "mindnet_note", "title": "mindnet note payload",
"type": "object", "type": "object",
"required": ["note_id", "title", "type", "status", "created", "path"],
"properties": { "properties": {
"note_id": { "type": "string" }, "note_id": { "type": "string" },
"title": { "type": "string" }, "title": { "type": ["string","null"] },
"type": { "type": "string" }, "type": { "type": ["string","null"] },
"status": { "type": "string" }, "status": { "type": ["string","null"] },
"created": { "type": "string" }, "created": { "type": ["string","null"] },
"updated": { "type": "string" }, "updated": { "type": ["string","null"] },
"tags": { "path": { "type": ["string","null"] },
"type": "array", "tags": { "type": ["array","null"], "items": { "type": "string" } },
"items": { "type": "string" } "area": { "type": ["string","null"] },
}, "project": { "type": ["string","null"] },
"area": { "type": "string" }, "source": { "type": ["string","null"] },
"project": { "type": "string" }, "lang": { "type": ["string","null"] },
"priority": { "type": "number" }, "slug": { "type": ["string","null"] },
"effort_min": { "type": "number" }, "aliases": { "type": ["array","null"], "items": { "type": "string" } },
"due": { "type": "string" },
"people": { "fulltext": { "type": ["string","null"] },
"type": "array", "references": { "type": ["array","null"], "items": { "type": "string" } },
"items": { "type": "string" }
}, "hash_fulltext": { "type": ["string","null"], "pattern": "^[a-f0-9]{64}$" },
"aliases": { "hash_signature": { "type": ["string","null"] },
"type": "array",
"items": { "type": "string" } "hash_body": { "type": ["string","null"], "pattern": "^[a-f0-9]{64}$" },
}, "hash_frontmatter": { "type": ["string","null"], "pattern": "^[a-f0-9]{64}$" },
"references": { "hash_full": { "type": ["string","null"], "pattern": "^[a-f0-9]{64}$" },
"type": "array",
"items": { "type": "string" } "hashes": {
}, "type": ["object","null"],
"depends_on": { "description": "Mapping: <mode>:<source>:<normalize> -> sha256 hex",
"type": "array", "patternProperties": {
"items": { "type": "string" } "^(body|frontmatter|full):(parsed|raw):(canonical|none)$": {
}, "type": "string",
"assigned_to": { "pattern": "^[a-f0-9]{64}$"
"type": "array", }
"items": { "type": "string" } },
}, "additionalProperties": false
"lang": { "type": "string" }, }
"path": { "type": "string" },
"hash_fulltext": { "type": "string" }
}, },
"required": ["note_id"],
"additionalProperties": true "additionalProperties": true
} }
+41
View File
@@ -0,0 +1,41 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/debug_note_payload.py
Zeigt, welche app.core.note_payload geladen wird, ruft make_note_payload auf
und druckt Typ/Preview der Rückgabe.
Aufruf:
python3 -m scripts.debug_note_payload --file ./test_vault/40_concepts/concept-alpha.md --vault-root ./test_vault
"""
import argparse, json, os, pprint
from app.core import note_payload as np
from app.core.parser import read_markdown
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--file", required=True)
ap.add_argument("--vault-root", default=None)
ap.add_argument("--hash-mode", default=None)
ap.add_argument("--hash-normalize", default=None)
ap.add_argument("--hash-source", default=None)
args = ap.parse_args()
print("module_path:", getattr(np, "__file__", "<unknown>"))
parsed = read_markdown(args.file)
res = np.make_note_payload(parsed, vault_root=args.vault_root,
hash_mode=args.hash_mode,
hash_normalize=args.hash_normalize,
hash_source=args.hash_source,
file_path=args.file)
print("return_type:", type(res).__name__)
if isinstance(res, dict):
print("keys:", list(res.keys()))
print(json.dumps(res, ensure_ascii=False, indent=2))
else:
preview = repr(res)
if len(preview) > 600: preview = preview[:600] + "…"
print("preview:", preview)
if __name__ == "__main__":
main()
+63
View File
@@ -0,0 +1,63 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
scripts/debug_qdrant_state.py
Zeigt Prefix, Collections und einfache Counts (notes/chunks/edges) + sample note_ids.
Aufruf:
export COLLECTION_PREFIX="mindnet"
python3 -m scripts.debug_qdrant_state
# oder:
python3 -m scripts.debug_qdrant_state --prefix mindnet
"""
from __future__ import annotations
import argparse, os, json
from app.core.qdrant import QdrantConfig, get_client
def count_points(client, collection: str) -> int:
try:
res = client.count(collection, exact=True)
return int(getattr(res, "count", 0))
except Exception:
pts, _ = client.scroll(collection, limit=1)
return 1 if pts else 0
def sample_ids(client, collection: str, id_key: str, limit: int = 5):
pts, _ = client.scroll(collection, with_payload=True, with_vectors=False, limit=limit)
out = []
for p in pts or []:
pl = p.payload or {}
if id_key in pl:
out.append(pl[id_key])
return out
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--prefix", default=os.environ.get("COLLECTION_PREFIX", "mindnet"))
args = ap.parse_args()
cfg = QdrantConfig.from_env()
cfg.prefix = args.prefix
client = get_client(cfg)
notes = f"{cfg.prefix}_notes"
chunks = f"{cfg.prefix}_chunks"
edges = f"{cfg.prefix}_edges"
print(json.dumps({
"prefix": cfg.prefix,
"collections": {"notes": notes, "chunks": chunks, "edges": edges},
"counts": {
"notes": count_points(client, notes),
"chunks": count_points(client, chunks),
"edges": count_points(client, edges),
},
"samples": {
"notes.note_id": sample_ids(client, notes, "note_id"),
"chunks.note_id": sample_ids(client, chunks, "note_id"),
"edges.note_id": sample_ids(client, edges, "note_id"),
}
}, ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
+165 -188
View File
@@ -1,249 +1,226 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """
Script: export_markdown.py — Qdrant → Markdown (Obsidian-kompatibel) Script: scripts/export_markdown.py — Qdrant → Markdown (Vault)
Version: 1.4.0 Version: 1.4.1
Datum: 2025-09-09 Datum: 2025-09-10
Kurzbeschreibung Funktion
---------------- --------
Exportiert Markdown-Notizen aus Qdrant in einen Zielordner (Vault). Exportiert Notes (Frontmatter + Body) aus Qdrant in einen Zielordner. Der Body wird
Rekonstruiert YAML-Frontmatter und Body. bevorzugt aus dem Feld `fulltext` rekonstruiert; falls leer/nicht vorhanden, aus Chunks
(Sortierung: seq → chunk_index → Nummer in chunk_id). Pfade werden **relativ** geschrieben.
Body-Rekonstruktions-Priorität (abwärtskompatibel): Optionen
1) notes.payload.fulltext (verlustfrei, wenn beim Import gespeichert) --------
2) ansonsten aus allen zugehörigen Chunks: payload.text → payload.content → payload.raw --out PATH Zielordner (erforderlich)
in stabiler, sequentieller Reihenfolge (seq/chunk_index/ID-Nummer) --prefix TEXT Collection-Prefix (CLI überschreibt ENV COLLECTION_PREFIX)
--note-id ID Nur eine Note exportieren
--overwrite Existierende Dateien überschreiben
--include-edges MODE none|yaml|footer (Default: none)
--flatten-paths Alle Dateien flach schreiben; Originalpfad in FM: orig_path
Wichtige Fixes ENV
-------------- ---
- **Pfad-Normalisierung**: erzwingt relative Pfade (führe führende '/' ab, backslashes → slashes), COLLECTION_PREFIX, QDRANT_URL | QDRANT_HOST/QDRANT_PORT | QDRANT_API_KEY
damit ``--out`` nicht ignoriert wird.
- **`--prefix` (optional)**: Überschreibt COLLECTION_PREFIX; ENV bleibt Default (rückwärtskompatibel).
ENV / Qdrant
------------
- QDRANT_URL (oder QDRANT_HOST/QDRANT_PORT)
- QDRANT_API_KEY (optional)
- COLLECTION_PREFIX (Default: mindnet)
Aufruf
------
python3 -m scripts.export_markdown --out ./_exportVault
python3 -m scripts.export_markdown --out ./_exportVault --note-id 20250821-foo
python3 -m scripts.export_markdown --out ./_exportVault --overwrite
python3 -m scripts.export_markdown --out ./_exportVault --prefix mindnet_dev # optional
Beispiele Beispiele
--------- ---------
COLLECTION_PREFIX=mindnet QDRANT_URL=http://127.0.0.1:6333 \\ export COLLECTION_PREFIX="mindnet"
python3 -m scripts.export_markdown --out ./_exportVault --overwrite python3 -m scripts.export_markdown --out ./_exportVault
"""
# Nur eine Note, Edges als YAML-Feld 'references'
python3 -m scripts.export_markdown --out ./_exportVault --note-id concept-alpha --include-edges yaml
# Flach schreiben mit Überschreiben
python3 -m scripts.export_markdown --out ./_exportVault --flatten-paths --overwrite
"""
from __future__ import annotations from __future__ import annotations
import argparse import argparse
import json
import os import os
import re import json
from typing import Dict, Iterable, List, Optional, Tuple from typing import Dict, List, Optional, Tuple, Any
import yaml import yaml
from qdrant_client.http import models as rest from qdrant_client.http import models as rest
from qdrant_client import QdrantClient
from app.core.qdrant import QdrantConfig, get_client, ensure_collections from app.core.qdrant import QdrantConfig, get_client
from app.core.qdrant import ensure_collections # safety
# ---------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------
# ----------------------------------------------------------------------------- def collections(prefix: str) -> Tuple[str, str, str]:
# Utilities
# -----------------------------------------------------------------------------
def _names(prefix: str) -> Tuple[str, str, str]:
return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges" return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges"
def _norm_rel_path(path: str) -> str:
p = (path or "").replace("\\", "/").lstrip("/")
return p if p else ""
def _ensure_dir(path: str) -> None: def _ensure_dir(path: str) -> None:
d = os.path.dirname(path) d = os.path.dirname(path)
if d and not os.path.isdir(d): if d and not os.path.exists(d):
os.makedirs(d, exist_ok=True) os.makedirs(d, exist_ok=True)
def _yaml_dump(data: Dict[str, Any]) -> str:
return yaml.safe_dump(data, allow_unicode=True, sort_keys=False).strip()
def _normalize_rel_path(p: str) -> str: def _frontmatter_block(fm: Dict[str, Any]) -> str:
"""Pfad relativ halten & normalisieren (slashes, führende / entfernen).""" y = _yaml_dump(fm)
p = (p or "").replace("\\", "/") return f"---\n{y}\n---\n"
return p.lstrip("/")
def _scroll_all(client, collection: str, flt: Optional[rest.Filter] = None) -> List[Any]:
def _to_md(frontmatter: dict, body: str) -> str:
fm = yaml.safe_dump(frontmatter, sort_keys=False, allow_unicode=True).strip()
return f"---\n{fm}\n---\n{(body or '').rstrip()}\n"
def _scroll_all(
client: QdrantClient,
col: str,
flt: Optional[rest.Filter] = None,
with_payload: bool = True,
with_vectors: bool = False,
limit: int = 256,
):
"""Scrollt durch alle Punkte einer Collection und liefert eine Liste mit Points."""
out = [] out = []
next_page = None nextp = None
while True: while True:
pts, next_page = client.scroll( pts, nextp = client.scroll(
collection_name=col, collection_name=collection,
with_payload=True,
with_vectors=False,
limit=256,
scroll_filter=flt, scroll_filter=flt,
with_payload=with_payload, offset=nextp,
with_vectors=with_vectors,
limit=limit,
offset=next_page,
) )
if not pts: if not pts:
break break
out.extend(pts) out.extend(pts)
if not next_page: if nextp is None:
break break
return out return out
def _reconstruct_body_from_chunks(chunks: List[Any]) -> str:
def seq_key(pl: Dict[str, Any]) -> Tuple[int, int, int]:
s = pl.get("seq")
ci = pl.get("chunk_index")
cid = pl.get("chunk_id") or ""
n = 0
if isinstance(cid, str) and "#" in cid:
try:
n = int(cid.rsplit("#", 1)[-1])
except Exception:
n = 0
return (int(s) if isinstance(s, int) else 0,
int(ci) if isinstance(ci, int) else 0,
n)
chunks_sorted = sorted(chunks, key=lambda p: seq_key(p.payload or {}))
texts: List[str] = []
for p in chunks_sorted:
pl = p.payload or {}
t = pl.get("text") or pl.get("content") or pl.get("raw") or ""
if isinstance(t, str) and t:
texts.append(t)
return "\n".join(texts).strip()
def _load_chunks_for_note(client: QdrantClient, chunks_col: str, note_id: str) -> List[dict]: def _collect_forward_refs_from_edges(edges: List[Any]) -> List[str]:
flt = rest.Filter(must=[rest.FieldCondition( refs = []
key="note_id", for p in edges:
match=rest.MatchValue(value=note_id), pl = p.payload or {}
)]) if pl.get("kind") == "references" and isinstance(pl.get("target_id"), str):
pts = _scroll_all(client, chunks_col, flt, with_payload=True, with_vectors=False) refs.append(pl["target_id"])
# Sortierung: bevorzugt seq → chunk_index → Nummer in id # de-dupe, preserve order
def _seq(pl: dict) -> Tuple[int, int, int]: seen = set()
s1 = pl.get("seq", pl.get("chunk_index", -1)) out = []
s2 = pl.get("chunk_index", -1) for r in refs:
# Nummer-Anteil aus "noteid#<n>" if r not in seen:
s3 = 0 seen.add(r)
try: out.append(r)
m = re.search(r"#(\\d+)$", pl.get("id") or "") return out
if m:
s3 = int(m.group(1))
except Exception:
pass
return (int(s1) if isinstance(s1, int) else -1, int(s2) if isinstance(s2, int) else -1, s3)
pts_sorted = sorted(pts, key=lambda p: _seq(p.payload or {})) # ---------------------------------------------------------------------
return [p.payload or {} for p in pts_sorted]
def _reconstruct_body(note_pl: dict, chunk_payloads: List[dict]) -> str:
# 1) Volltext vorhanden?
fulltext = note_pl.get("fulltext")
if isinstance(fulltext, str) and fulltext.strip():
return fulltext
# 2) Aus Chunks zusammensetzen: text → content → raw
parts: List[str] = []
for ch in chunk_payloads:
text = ch.get("text") or ch.get("content") or ch.get("raw")
if isinstance(text, str) and text.strip():
parts.append(text.rstrip())
return ("\n\n".join(parts)).rstrip() + ("\n" if parts else "")
def _export_one_note(
client: QdrantClient,
prefix: str,
note_pl: dict,
out_root: str,
overwrite: bool,
) -> dict:
notes_col, chunks_col, _ = _names(prefix)
note_id = note_pl.get("note_id") or note_pl.get("id")
# Pfad robust bestimmen und relativ halten
path = note_pl.get("path") or f"{note_id}.md"
path = _normalize_rel_path(path)
out_path = os.path.join(out_root, path).replace("\\", "/")
# Frontmatter aus Payload zurückführen (nur bekannte Felder)
fm: Dict[str, object] = {}
for k in [
"title", "id", "type", "status", "created", "updated", "tags",
"priority", "effort_min", "due", "people", "aliases",
"depends_on", "assigned_to", "lang",
]:
v = note_pl.get(k) if k in note_pl else note_pl.get(f"note_{k}")
if v not in (None, [], ""):
fm[k] = v
# Mindestfelder
if "id" not in fm and note_id:
fm["id"] = note_id
if "title" not in fm and note_pl.get("title"):
fm["title"] = note_pl["title"]
# Body beschaffen
chunks = _load_chunks_for_note(client, chunks_col, note_id)
body = _reconstruct_body(note_pl, chunks)
# Schreiben?
if os.path.exists(out_path) and not overwrite:
return {"note_id": note_id, "path": path, "status": "skip_exists"}
_ensure_dir(out_path)
with open(out_path, "w", encoding="utf-8") as f:
f.write(_to_md(fm, body))
return {"note_id": note_id, "path": path, "status": "written"}
# -----------------------------------------------------------------------------
# Main # Main
# ----------------------------------------------------------------------------- # ---------------------------------------------------------------------
def main() -> None: def main() -> None:
ap = argparse.ArgumentParser() ap = argparse.ArgumentParser()
ap.add_argument("--out", required=True, help="Zielordner für den Export-Vault") ap.add_argument("--out", required=True, help="Zielordner für exportierte Markdown-Dateien")
ap.add_argument("--note-id", help="Nur eine Note exportieren (Note-ID)") ap.add_argument("--prefix", help="Collection-Prefix (überschreibt ENV COLLECTION_PREFIX)")
ap.add_argument("--overwrite", action="store_true", help="Bestehende Dateien überschreiben") ap.add_argument("--note-id", help="Nur eine bestimmte Note-ID exportieren")
ap.add_argument("--prefix", help="(Optional) überschreibt COLLECTION_PREFIX aus ENV") ap.add_argument("--overwrite", action="store_true", help="Existierende Dateien überschreiben")
ap.add_argument("--include-edges", choices=["none", "yaml", "footer"], default="none",
help="Forward-Links mit exportieren (aus Edges oder Note-Payload)")
ap.add_argument("--flatten-paths", action="store_true", help="Alle Dateien flach schreiben (orig_path in Frontmatter)")
args = ap.parse_args() args = ap.parse_args()
# Qdrant-Konfiguration
cfg = QdrantConfig.from_env() cfg = QdrantConfig.from_env()
if args.prefix: if args.prefix:
cfg.prefix = args.prefix # abwärtskompatibel: ENV bleibt Default cfg.prefix = args.prefix.strip()
client = get_client(cfg) client = get_client(cfg)
ensure_collections(client, cfg.prefix, cfg.dim) ensure_collections(client, cfg.prefix, cfg.dim)
notes_col, _, _ = _names(cfg.prefix) out_root = os.path.abspath(args.out)
os.makedirs(out_root, exist_ok=True)
# Notes holen (optional gefiltert) notes_col, chunks_col, edges_col = collections(cfg.prefix)
# Filter nach note-id (optional)
flt = None flt = None
if args.note_id: if args.note_id:
flt = rest.Filter(must=[rest.FieldCondition( flt = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=args.note_id))])
key="note_id",
match=rest.MatchValue(value=args.note_id),
)])
note_pts = _scroll_all(client, notes_col, flt, with_payload=True, with_vectors=False) notes = _scroll_all(client, notes_col, flt)
if not note_pts: total = 0
print(json.dumps({"exported": 0, "out": args.out, "message": "Keine Notes gefunden."}, ensure_ascii=False)) for n in notes:
return pl = n.payload or {}
nid = pl.get("note_id")
rel_path = _norm_rel_path(pl.get("path") or "")
if args.flatten_paths or not rel_path:
fname = f"{(nid or 'note')}.md"
out_path = os.path.join(out_root, fname)
else:
out_path = os.path.join(out_root, rel_path)
out_path = out_path.replace("\\", "/")
_ensure_dir(out_path)
results = [] # Frontmatter aufbauen (nur sinnvolle Felder)
for p in note_pts: fm_fields = ["id","title","type","status","created","updated","tags","area","project","source","lang","slug","aliases"]
pl = p.payload or {} fm: Dict[str, Any] = {}
try: fm["id"] = nid
res = _export_one_note(client, cfg.prefix, pl, args.out, args.overwrite) for k in fm_fields:
except Exception as e: if k == "id":
res = {"note_id": pl.get("note_id") or pl.get("id"), "error": str(e)} continue
results.append(res) if k in pl and pl[k] is not None:
fm[k] = pl[k]
if args.flatten_paths and rel_path:
fm["orig_path"] = rel_path
print(json.dumps({ # Body ermitteln (fulltext oder Chunks)
"exported": len([r for r in results if r.get("status") == "written"]), body = (pl.get("fulltext") or "").strip()
"skipped": len([r for r in results if r.get("status") == "skip_exists"]), if not body:
"out": args.out, flt_chunks = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=nid))])
"details": results, chunks = _scroll_all(client, chunks_col, flt_chunks)
}, ensure_ascii=False)) body = _reconstruct_body_from_chunks(chunks)
# Edges (optional)
refs: List[str] = []
if args.include_edges != "none":
# aus Note-Payload, falls vorhanden
if isinstance(pl.get("references"), list) and pl["references"]:
refs = [r for r in pl["references"] if isinstance(r, str)]
else:
flt_edges = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=nid))])
edges = _scroll_all(client, edges_col, flt_edges)
refs = _collect_forward_refs_from_edges(edges)
if args.include_edges == "yaml" and refs:
fm["references"] = refs
# Datei schreiben
if (not args.overwrite) and os.path.exists(out_path):
print(json.dumps({"note_id": nid, "path": out_path, "decision": "skip-exists"}))
continue
content = _frontmatter_block(fm) + (body + "\n" if body else "")
if args.include_edges == "footer" and refs:
content += "\n---\nLinks:\n" + "\n".join(f"- [[{r}]]" for r in refs) + "\n"
with open(out_path, "w", encoding="utf-8") as f:
f.write(content)
print(json.dumps({"note_id": nid, "path": out_path, "decision": "write"}))
total += 1
print(f"Done. Exported notes: {total}")
if __name__ == "__main__": if __name__ == "__main__":
+312 -132
View File
@@ -1,48 +1,68 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """
Script: import_markdown.py — Markdown → Qdrant (Notes, Chunks, Edges) Script: scripts/import_markdown.py — Markdown → Qdrant (Notes, Chunks, Edges)
Version: 3.2.0 Version: 3.7.2
Datum: 2025-09-09 Datum: 2025-09-30
Kurzbeschreibung Kurzbeschreibung
---------------- ----------------
Liest Markdown-Dateien aus einem Vault ein und schreibt Notes, Chunks und Edges - Liest Markdown-Dateien ein und erzeugt Notes/Chunks/Edges **idempotent**.
idempotent nach Qdrant. Change-Detection basiert standardmäßig auf dem **Body-Hash**. - Änderungserkennung „Option C“: mehrere Hash-Varianten werden parallel in der Note
Neu: Hash-Modus und Normalisierung sind auch per **CLI** steuerbar. gespeichert (Feld `hashes` mit Schlüsseln `<mode>:<source>:<normalize>`). Der Vergleich
nutzt NUR den aktuellen Modus-Key — ein Moduswechsel triggert keine Massenänderungen mehr.
- „Erstimport-Fix“: Bei leerem Qdrant gilt Create-Fall automatisch als geändert.
- `--baseline-modes`: fehlende Hash-Varianten still nachtragen (nur Notes upserten).
- `--sync-deletes`: gezielte Lösch-Synchronisation (Dry-Run + Apply).
- `--only-path`: exakt **eine** Datei (Pfad) importieren — nützlich für Diagnosefälle.
ENV / Qdrant Neu in 3.7.1/3.7.2
------------------
- Chunk-Payloads: `window` (für Embeddings), `text` (überlappungsfrei, verlustfrei rekonstruierbar),
`start/end/overlap_*`. Embeddings nutzen `window`.
- **3.7.2:** Edges-Fehler führen nicht mehr zum Abbruch der gesamten Note; Note/Chunks werden trotzdem geschrieben.
Hash/Compare Konfiguration
--------------------------
- Vergleichsmodus:
--hash-mode body|frontmatter|full
oder ENV: MINDNET_HASH_MODE | MINDNET_HASH_COMPARE
- Quelle:
--hash-source parsed|raw (ENV: MINDNET_HASH_SOURCE, Default parsed)
- Normalisierung:
--hash-normalize canonical|none (ENV: MINDNET_HASH_NORMALIZE, Default canonical)
- Optional: --compare-text (oder ENV MINDNET_COMPARE_TEXT=true) vergleicht zusätzlich
den parsed Body-Text direkt.
Qdrant / ENV
------------ ------------
- QDRANT_URL (oder QDRANT_HOST/QDRANT_PORT) - QDRANT_URL | QDRANT_HOST/QDRANT_PORT | QDRANT_API_KEY
- QDRANT_API_KEY (optional) - COLLECTION_PREFIX (Default: mindnet), via --prefix überschreibbar
- COLLECTION_PREFIX (Default: mindnet)
- VECTOR_DIM (Default: 384) - VECTOR_DIM (Default: 384)
- MINDNET_HASH_MODE: "body" (Default) | "frontmatter" | "body+frontmatter" - MINDNET_NOTE_SCOPE_REFS: true|false (Default: false)
- MINDNET_HASH_NORMALIZE: "canonical" (Default) | "none"
CLI (übersteuert ENV) Beispiele
--------------------- ---------
--hash-mode body|frontmatter|body+frontmatter # Standard (Body, parsed, canonical)
--hash-normalize canonical|none
Aufruf
------
python3 -m scripts.import_markdown --vault ./vault 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
"""
# Erstimport nach truncate (Create-Fall)
python3 -m scripts.import_markdown --vault ./vault --apply --purge-before-upsert
# Nur eine Datei (Diagnose)
python3 -m scripts.import_markdown --vault ./vault --only-path ./vault/30_projects/project-demo.md --apply
# Sync-Deletes (Dry-Run → Apply)
python3 -m scripts.import_markdown --vault ./vault --sync-deletes
python3 -m scripts.import_markdown --vault ./vault --sync-deletes --apply
"""
from __future__ import annotations from __future__ import annotations
import argparse import argparse
import json import json
import os import os
import sys import sys
from typing import Dict, List, Optional, Tuple from typing import Dict, List, Optional, Tuple, Any, Set
from dotenv import load_dotenv from dotenv import load_dotenv
from qdrant_client.http import models as rest from qdrant_client.http import models as rest
@@ -51,12 +71,20 @@ from app.core.parser import (
read_markdown, read_markdown,
normalize_frontmatter, normalize_frontmatter,
validate_required_frontmatter, validate_required_frontmatter,
extract_wikilinks,
) )
from app.core.note_payload import make_note_payload from app.core.note_payload import make_note_payload
from app.core.chunker import assemble_chunks from app.core.chunker import assemble_chunks
from app.core.chunk_payload import make_chunk_payloads from app.core.chunk_payload import make_chunk_payloads
from app.core.qdrant import QdrantConfig, get_client, ensure_collections try:
from app.core.derive_edges import build_edges_for_note
except Exception: # pragma: no cover
from app.core.edges import build_edges_for_note # type: ignore
from app.core.qdrant import (
QdrantConfig,
get_client,
ensure_collections,
ensure_payload_indexes,
)
from app.core.qdrant_points import ( from app.core.qdrant_points import (
points_for_chunks, points_for_chunks,
points_for_note, points_for_note,
@@ -65,15 +93,14 @@ from app.core.qdrant_points import (
) )
try: try:
from app.core.embed import embed_texts, embed_one # optional from app.core.embed import embed_texts # optional
except Exception: except Exception:
embed_texts = None embed_texts = None
embed_one = None
# ----------------------------------------------------------------------------- # ---------------------------------------------------------------------
# Hilfsfunktionen # Helper
# ----------------------------------------------------------------------------- # ---------------------------------------------------------------------
def iter_md(root: str) -> List[str]: def iter_md(root: str) -> List[str]:
out: List[str] = [] out: List[str] = []
@@ -88,15 +115,14 @@ def iter_md(root: str) -> List[str]:
out.append(p) out.append(p)
return sorted(out) return sorted(out)
def collections(prefix: str) -> Tuple[str, str, str]: def collections(prefix: str) -> Tuple[str, str, str]:
return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges" 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) notes_col, _, _ = collections(prefix)
f = rest.Filter(must=[rest.FieldCondition( f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
key="note_id",
match=rest.MatchValue(value=note_id),
)])
points, _ = client.scroll( points, _ = client.scroll(
collection_name=notes_col, collection_name=notes_col,
scroll_filter=f, scroll_filter=f,
@@ -106,33 +132,77 @@ def fetch_existing_note_hash(client, prefix: str, note_id: str) -> Optional[str]
) )
if not points: if not points:
return None return None
pl = points[0].payload or {} return points[0].payload or {}
return pl.get("hash_fulltext")
def list_qdrant_note_ids(client, prefix: str) -> Set[str]:
notes_col, _, _ = collections(prefix)
out: Set[str] = set()
next_page = None
while True:
pts, next_page = client.scroll(
collection_name=notes_col,
with_payload=True,
with_vectors=False,
limit=256,
offset=next_page,
)
if not pts:
break
for p in pts:
pl = p.payload or {}
nid = pl.get("note_id")
if isinstance(nid, str):
out.add(nid)
if next_page is None:
break
return out
def purge_note_artifacts(client, prefix: str, note_id: str) -> None: def purge_note_artifacts(client, prefix: str, note_id: str) -> None:
_, chunks_col, edges_col = collections(prefix) _, chunks_col, edges_col = collections(prefix)
f_chunks = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))]) filt = 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) for col in (chunks_col, edges_col):
should = [ try:
rest.FieldCondition(key="source_id", match=rest.MatchText(text=f"{note_id}#")), client.delete(
rest.FieldCondition(key="target_id", match=rest.MatchText(text=f"{note_id}#")), collection_name=col,
rest.FieldCondition(key="source_id", match=rest.MatchValue(value=note_id)), points_selector=rest.FilterSelector(filter=filt),
rest.FieldCondition(key="target_id", match=rest.MatchValue(value=note_id)), wait=True
] )
f_edges = rest.Filter(should=should) except Exception as e:
client.delete(collection_name=edges_col, points_selector=f_edges, wait=True) print(json.dumps({"note_id": note_id, "warn": f"delete in {col} via filter failed: {e}"}))
def _normalize_rel_path(abs_path: str, vault_root: str) -> str:
try:
rel = os.path.relpath(abs_path, vault_root)
except Exception:
rel = abs_path
return rel.replace("\\", "/").lstrip("/")
# ----------------------------------------------------------------------------- def delete_note_everywhere(client, prefix: str, note_id: str) -> None:
notes_col, chunks_col, edges_col = collections(prefix)
filt = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
for col in (edges_col, chunks_col, notes_col):
try:
client.delete(
collection_name=col,
points_selector=rest.FilterSelector(filter=filt),
wait=True
)
except Exception as e:
print(json.dumps({"note_id": note_id, "warn": f"delete in {col} failed: {e}"}))
def _resolve_mode(val: Optional[str]) -> str:
v = (val or os.environ.get("MINDNET_HASH_MODE") or os.environ.get("MINDNET_HASH_COMPARE") or "body").strip().lower()
if v in ("full", "fulltext", "body+frontmatter", "bodyplusfrontmatter"):
return "full"
if v in ("frontmatter", "fm"):
return "frontmatter"
return "body"
def _env(key: str, default: str) -> str:
return (os.environ.get(key) or default).strip().lower()
# ---------------------------------------------------------------------
# Main # Main
# ----------------------------------------------------------------------------- # ---------------------------------------------------------------------
def main() -> None: def main() -> None:
load_dotenv() load_dotenv()
@@ -142,126 +212,236 @@ def main() -> None:
ap.add_argument("--purge-before-upsert", action="store_true", ap.add_argument("--purge-before-upsert", action="store_true",
help="Vor Upsert Chunks & Edges der GEÄNDERTEN Note löschen") help="Vor Upsert Chunks & Edges der GEÄNDERTEN Note löschen")
ap.add_argument("--note-id", help="Nur eine bestimmte Note-ID verarbeiten") ap.add_argument("--note-id", help="Nur eine bestimmte Note-ID verarbeiten")
ap.add_argument("--only-path", help="Exakt diesen Markdown-Pfad verarbeiten (ignoriert --note-id)")
ap.add_argument("--embed-note", action="store_true", help="Optional: Note-Volltext einbetten") ap.add_argument("--embed-note", action="store_true", help="Optional: Note-Volltext einbetten")
ap.add_argument("--force-replace", action="store_true", ap.add_argument("--force-replace", action="store_true",
help="Änderungserkennung ignorieren und immer upserten (+ optional Purge)") help="Änderungserkennung ignorieren und immer upserten (+ optional Purge)")
# NEU: Hash-Steuerung per CLI ap.add_argument("--hash-mode", choices=["body", "frontmatter", "full"], default=None,
ap.add_argument("--hash-mode", choices=["body", "frontmatter", "body+frontmatter"], default=None) help="Vergleichsmodus (Body | Frontmatter | Full)")
ap.add_argument("--hash-normalize", choices=["canonical", "none"], default=None) 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/backlink:note (Default: aus)")
ap.add_argument("--debug-hash-diff", action="store_true",
help="(reserviert) optionaler Body-Diff")
ap.add_argument("--compare-text", action="store_true",
help="Parsed fulltext zusätzlich direkt vergleichen (über Hash hinaus)")
ap.add_argument("--baseline-modes", action="store_true",
help="Fehlende Hash-Varianten im Feld 'hashes' still nachtragen (Upsert NUR Notes)")
ap.add_argument("--sync-deletes", action="store_true",
help="Notes/Chunks/Edges löschen, die in Qdrant existieren aber im Vault fehlen (Dry-Run; mit --apply ausführen)")
ap.add_argument("--prefix", help="Collection-Prefix (überschreibt ENV COLLECTION_PREFIX)")
args = ap.parse_args() args = ap.parse_args()
mode = _resolve_mode(args.hash_mode) # body|frontmatter|full
src = _env("MINDNET_HASH_SOURCE", args.hash_source or "parsed") # parsed|raw
norm = _env("MINDNET_HASH_NORMALIZE", args.hash_normalize or "canonical") # canonical|none
note_scope_refs_env = (_env("MINDNET_NOTE_SCOPE_REFS", "false") == "true")
note_scope_refs = args.note_scope_refs or note_scope_refs_env
compare_text = args.compare_text or (_env("MINDNET_COMPARE_TEXT", "false") == "true")
cfg = QdrantConfig.from_env() cfg = QdrantConfig.from_env()
if args.prefix:
cfg.prefix = args.prefix.strip()
client = get_client(cfg) client = get_client(cfg)
ensure_collections(client, cfg.prefix, cfg.dim) 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) root = os.path.abspath(args.vault)
files = iter_md(root)
# Dateiliste bestimmen
if args.only_path:
only = os.path.abspath(args.only_path)
files = [only]
else:
files = iter_md(root)
if not files: if not files:
print("Keine Markdown-Dateien gefunden.", file=sys.stderr) print("Keine Markdown-Dateien gefunden.", file=sys.stderr)
sys.exit(2) sys.exit(2)
# Optional: Sync-Deletes vorab
if args.sync_deletes:
vault_note_ids: Set[str] = set()
for path in files:
try:
parsed = read_markdown(path)
if not parsed:
continue
fm = normalize_frontmatter(parsed.frontmatter)
nid = fm.get("id")
if isinstance(nid, str):
vault_note_ids.add(nid)
except Exception:
continue
qdrant_note_ids = list_qdrant_note_ids(client, cfg.prefix)
to_delete = sorted(qdrant_note_ids - vault_note_ids)
print(json.dumps({
"action": "sync-deletes",
"prefix": cfg.prefix,
"qdrant_total": len(qdrant_note_ids),
"vault_total": len(vault_note_ids),
"to_delete_count": len(to_delete),
"to_delete": to_delete[:50] + (["…"] if len(to_delete) > 50 else [])
}, ensure_ascii=False))
if args.apply and to_delete:
for nid in to_delete:
print(json.dumps({"action": "delete", "note_id": nid, "decision": "apply"}))
delete_note_everywhere(client, cfg.prefix, nid)
key_current = f"{mode}:{src}:{norm}"
processed = 0 processed = 0
for path in files: for path in files:
parsed = read_markdown(path) # -------- Parse & Validate --------
fm = normalize_frontmatter(parsed.frontmatter)
try: try:
validate_required_frontmatter(fm) parsed = read_markdown(path)
except Exception as e: except Exception as e:
print(json.dumps({"path": path, "error": f"Frontmatter invalid: {e}"})) print(json.dumps({"path": path, "error": f"read_markdown failed: {type(e).__name__}: {e}"}))
continue
if parsed is None:
print(json.dumps({"path": path, "error": "read_markdown returned None"}))
continue continue
if args.note_id and fm.get("id") != args.note_id: try:
fm = normalize_frontmatter(parsed.frontmatter)
validate_required_frontmatter(fm)
except Exception as e:
print(json.dumps({"path": path, "error": f"Frontmatter invalid: {type(e).__name__}: {e}"}))
continue
if args.note_id and not args.only_path and fm.get("id") != args.note_id:
continue continue
processed += 1 processed += 1
# Note-Payload (mit expliziten Hash-Parametern) # -------- Build new payload (includes 'hashes') --------
note_pl = make_note_payload(parsed, vault_root=root, note_pl = make_note_payload(
hash_mode=args.hash_mode, hash_normalize=args.hash_normalize) parsed,
if "fulltext" not in (note_pl or {}): vault_root=root,
note_pl["fulltext"] = parsed.body or "" hash_mode=mode,
if note_pl.get("path"): hash_normalize=norm,
note_pl["path"] = _normalize_rel_path( hash_source=src,
os.path.join(root, note_pl["path"]) if not os.path.isabs(note_pl["path"]) else note_pl["path"], root file_path=path,
) )
else: if not note_pl.get("fulltext"):
note_pl["path"] = _normalize_rel_path(parsed.path, root) note_pl["fulltext"] = getattr(parsed, "body", "") or ""
note_id = note_pl["note_id"] note_id = note_pl.get("note_id") or fm.get("id")
if not note_id:
print(json.dumps({"path": path, "error": "Missing note_id after payload build"}))
continue
# Change-Detection # -------- Fetch old payload --------
new_hash = note_pl.get("hash_fulltext") old_payload = None if args.force_replace else fetch_existing_note_payload(client, cfg.prefix, note_id)
old_hash = None if args.force_replace else fetch_existing_note_hash(client, cfg.prefix, note_id) has_old = old_payload is not None
changed = args.force_replace or (old_hash != new_hash)
# Chunks + Embeddings (Nullvektor-Fallback) old_hashes = (old_payload or {}).get("hashes") or {}
chunks = assemble_chunks(fm["id"], parsed.body, fm.get("type", "concept")) old_hash_exact = old_hashes.get(key_current)
chunk_pls = make_chunk_payloads(fm, note_pl["path"], chunks) new_hash_exact = (note_pl.get("hashes") or {}).get(key_current)
if embed_texts: needs_baseline = (old_hash_exact is None)
vecs = embed_texts([getattr(c, "text", "") for c in chunks])
else:
vecs = [[0.0] * cfg.dim for _ in chunks]
# Edges (leichtgewichtig direkt hier ableiten) hash_changed = (old_hash_exact is not None and new_hash_exact is not None and old_hash_exact != new_hash_exact)
# 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())
# Zusammenfassung text_changed = False
if compare_text:
old_text = (old_payload or {}).get("fulltext") or ""
new_text = note_pl.get("fulltext") or ""
text_changed = (old_text != new_text)
changed = args.force_replace or (not has_old) or hash_changed or text_changed
do_baseline_only = (args.baseline_modes and has_old and needs_baseline and not changed)
# -------- Chunks / Embeddings --------
chunk_pls: List[Dict[str, Any]] = []
try:
body_text = getattr(parsed, "body", "") or ""
chunks = assemble_chunks(fm["id"], body_text, fm.get("type", "concept"))
chunk_pls = make_chunk_payloads(fm, note_pl["path"], chunks, note_text=body_text)
except Exception as e:
print(json.dumps({"path": path, "note_id": note_id, "error": f"chunk build failed: {type(e).__name__}: {e}"}))
continue
vecs: List[List[float]] = [[0.0] * cfg.dim for _ in chunk_pls]
if embed_texts and chunk_pls:
try:
texts_for_embed = [(pl.get("window") or pl.get("text") or "") for pl in chunk_pls]
vecs = embed_texts(texts_for_embed)
except Exception as e:
print(json.dumps({"path": path, "note_id": note_id, "warn": f"embed_texts failed, using zeros: {e}"}))
# -------- Edges (robust) --------
edges: List[Dict[str, Any]] = []
edges_failed = False
if changed and (not do_baseline_only):
try:
note_refs = note_pl.get("references") or []
edges = build_edges_for_note(
note_id,
chunk_pls,
note_level_references=note_refs,
include_note_scope_refs=note_scope_refs,
)
except Exception as e:
edges_failed = True
edges = []
# WICHTIG: Wir brechen NICHT mehr ab — Note & Chunks werden geschrieben.
print(json.dumps({"path": path, "note_id": note_id, "warn": f"build_edges_for_note failed, skipping edges: {type(e).__name__}: {e}"}))
# -------- Summary --------
summary = { summary = {
"note_id": note_id, "note_id": note_id,
"title": fm.get("title"), "title": fm.get("title"),
"chunks": len(chunk_pls), "chunks": len(chunk_pls),
"edges": len(edges), "edges": len(edges),
"edges_failed": edges_failed,
"changed": changed, "changed": changed,
"decision": ("apply" if args.apply and changed else "needs_baseline_for_mode": needs_baseline,
"decision": ("baseline-only" if args.apply and do_baseline_only else
"apply" if args.apply and changed else
"apply-skip-unchanged" if args.apply and not changed else "apply-skip-unchanged" if args.apply and not changed else
"dry-run"), "dry-run"),
"path": note_pl["path"], "path": note_pl["path"],
"hash_mode": args.hash_mode or os.environ.get("MINDNET_HASH_MODE", "body"), "hash_mode": mode,
"hash_normalize": args.hash_normalize or os.environ.get("MINDNET_HASH_NORMALIZE", "canonical"), "hash_normalize": norm,
"hash_old": old_hash, "hash_source": src,
"hash_new": new_hash, "prefix": cfg.prefix,
} }
print(json.dumps(summary, ensure_ascii=False)) print(json.dumps(summary, ensure_ascii=False))
# -------- Writes --------
if not args.apply: if not args.apply:
continue continue
if changed and args.purge_before_upsert: if do_baseline_only:
purge_note_artifacts(client, cfg.prefix, note_id) merged_hashes = {}
merged_hashes.update(old_hashes)
merged_hashes.update(note_pl.get("hashes") or {})
if old_payload:
note_pl["hash_fulltext"] = old_payload.get("hash_fulltext", note_pl.get("hash_fulltext"))
note_pl["hash_signature"] = old_payload.get("hash_signature", note_pl.get("hash_signature"))
note_pl["hashes"] = merged_hashes
notes_name, note_pts = points_for_note(cfg.prefix, note_pl, None, cfg.dim)
upsert_batch(client, notes_name, note_pts)
continue
if not changed:
continue
if args.purge_before_upsert and has_old:
try:
purge_note_artifacts(client, cfg.prefix, note_id)
except Exception as e:
print(json.dumps({"path": path, "note_id": note_id, "warn": f"purge failed: {e}"}))
notes_name, note_pts = points_for_note(cfg.prefix, note_pl, None, cfg.dim) notes_name, note_pts = points_for_note(cfg.prefix, note_pl, None, cfg.dim)
upsert_batch(client, notes_name, note_pts) upsert_batch(client, notes_name, note_pts)
if chunk_pls:
chunks_name, chunk_pts = points_for_chunks(cfg.prefix, chunk_pls, vecs) chunks_name, chunk_pts = points_for_chunks(cfg.prefix, chunk_pls, vecs)
upsert_batch(client, chunks_name, chunk_pts) upsert_batch(client, chunks_name, chunk_pts)
if edges:
edges_name, edge_pts = points_for_edges(cfg.prefix, edges) edges_name, edge_pts = points_for_edges(cfg.prefix, edges)
upsert_batch(client, edges_name, edge_pts) upsert_batch(client, edges_name, edge_pts)
print(f"Done. Processed notes: {processed}") print(f"Done. Processed notes: {processed}")
+18 -14
View File
@@ -3,31 +3,32 @@
""" """
make_test_vault.py — erzeugt einen minimalen, nachvollziehbaren Test-Vault make_test_vault.py — erzeugt einen minimalen, nachvollziehbaren Test-Vault
Version: 1.1 (2025-09-05) Version: 1.2 (2025-09-09)
Änderungen ggü. 1.0: Änderungen ggü. 1.1:
- created/updated werden als QUOTED ISO-Strings geschrieben, damit der YAML-Parser - Fügt **externe Links** (http/mailto) in `exp-two.md` hinzu, damit der Chunk-Payload-Exporter
sie nicht in datetime-Objekte konvertiert (Schema verlangt strings). `external_links` realistisch testen kann.
- Kommentare/Output gestrafft. - Kleine Textanpassungen zur stabilen Chunk-Bildung (Absatzstruktur).
Zweck Zweck
- Kleiner Obsidian-ähnlicher Vault zum Durchspielen des Importers (Chunks/Edges). - Kleiner Obsidian-ähnlicher Vault zum Durchspielen des Importers (Chunks/Edges).
- Szenarien: leere Links, spätere Anlage fehlender Noten, Chunk-Neuaufteilung. - Szenarien: leere Links, spätere Anlage fehlender Noten, Chunk-Neuaufteilung, externe Links.
Struktur (Default: ./test_vault) Struktur (Default: ./test_vault)
- 40_concepts/concept-alpha.md - 40_concepts/concept-alpha.md
- 20_experiences/exp-one.md (verlinkt auf [[concept-alpha]] und [[missing-note]]) - 20_experiences/exp-one.md (verlinkt auf [[concept-alpha]] und [[missing-note]])
- 20_experiences/exp-two.md (verlinkt auf [[concept-alpha]]) - 20_experiences/exp-two.md (verlinkt auf [[concept-alpha]] + externe Links)
- 30_projects/project-demo.md (verlinkt auf [[concept-alpha]] und [[exp-one]]) - 30_projects/project-demo.md (verlinkt auf [[concept-alpha]] und [[exp-one]])
Voraussetzungen Voraussetzungen
- Keine. Rein Dateigenerierung. - Keine. Rein Dateigenerierung.
Aufruf Aufruf
python3 -m scripts.make_test_vault [--out ./test_vault] [--force] python3 -m scripts.make_test_vault [--out ./test_vault] [--force] [--with-missing]
Parameter Parameter
--out Zielverzeichnis (Standard: ./test_vault) --out Zielverzeichnis (Standard: ./test_vault)
--force Bestehenden Ordner löschen und neu anlegen. --force Bestehenden Ordner löschen und neu anlegen.
--with-missing Auch die 'missing-note' direkt anlegen (Standard: erst im 2. Lauf)
Hinweise für Tests Hinweise für Tests
1) Erster Import (dry-run oder --apply): Es gibt einen „leeren“ Link [[missing-note]]. 1) Erster Import (dry-run oder --apply): Es gibt einen „leeren“ Link [[missing-note]].
@@ -35,6 +36,7 @@ Hinweise für Tests
-> Erwartung: Edges für ehemals leeren Link werden korrekt nachgezogen (references + backlink). -> Erwartung: Edges für ehemals leeren Link werden korrekt nachgezogen (references + backlink).
3) Ändere den Body von exp-one.md so, dass andere Chunk-Grenzen entstehen und importiere erneut: 3) Ändere den Body von exp-one.md so, dass andere Chunk-Grenzen entstehen und importiere erneut:
-> Erwartung: Chunks/Edges/Note werden für betroffene Noten aktualisiert. -> Erwartung: Chunks/Edges/Note werden für betroffene Noten aktualisiert.
4) Prüfe externe Links (verify_chunk_texts.py betrifft nur Text; externe Links siehst du in chunk_payloads).
Kompatibel mit: Kompatibel mit:
- note.schema.json: 'created'/'updated' müssen strings sein. (Wichtig!) - note.schema.json: 'created'/'updated' müssen strings sein. (Wichtig!)
@@ -52,7 +54,6 @@ def iso_now() -> str:
def q(s: str) -> str: def q(s: str) -> str:
# Sicheres Quoten für YAML-Frontmatter # Sicheres Quoten für YAML-Frontmatter
# (einfaches doppelt-Quoten reicht hier, da wir keine eingebetteten """ verwenden)
return f"\"{s}\"" return f"\"{s}\""
TEMPLATE_CONCEPT = """--- TEMPLATE_CONCEPT = """---
@@ -66,7 +67,7 @@ tags: ["area/mindnet","type/concept","topic/test"]
--- ---
## Beschreibung ## Beschreibung
Dies ist ein einfaches Konzept für Testzwecke. Dies ist ein einfaches Konzept für Testzwecke. Es wird von anderen Notizen referenziert.
## Mögliche Verbindungen ## Mögliche Verbindungen
- [[exp-one]] - [[exp-one]]
@@ -109,10 +110,12 @@ tags: ["area/mindnet","type/experience","topic/test"]
--- ---
## Kontext ## Kontext
Zweite Experience, die auf dasselbe Konzept verweist. Zweite Experience, die auf dasselbe Konzept verweist, ergänzt um **externe Links**.
## Beobachtung ## Beobachtung
Verweis auf [[concept-alpha]]. Verweis auf [[concept-alpha]]. Zusätzliche Ressourcen:
- Link: [Beispielseite](https://example.com "Referenz")
- Kontakt: [E-Mail](mailto:info@example.com)
## Mögliche Verbindungen ## Mögliche Verbindungen
- [[concept-alpha]] - [[concept-alpha]]
@@ -218,6 +221,7 @@ def main():
print(" 1) Zuerst ohne missing-note anlegen (Standard), importieren, Edges prüfen.") print(" 1) Zuerst ohne missing-note anlegen (Standard), importieren, Edges prüfen.")
print(" 2) Dann erneut ausführen mit --force --with-missing (missing-note wird erzeugt),") print(" 2) Dann erneut ausführen mit --force --with-missing (missing-note wird erzeugt),")
print(" und Import wiederholen → Edges/Backlinks sollten nachgezogen werden.") print(" und Import wiederholen → Edges/Backlinks sollten nachgezogen werden.")
print(" 3) In exp-two.md sind **externe Links** enthalten → prüfe `external_links` in Chunk-Payloads.")
if __name__ == "__main__": if __name__ == "__main__":
main() main()
+92
View File
@@ -0,0 +1,92 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Script: scripts/report_hashes.py — Übersicht & Lücken bei Mehrfach-Hashes
Version: 1.0.0
Datum: 2025-09-10
Funktion
--------
Listet je Note die vorhandenen Einträge im Feld `hashes` (Signaturen: <mode>:<source>:<normalize>)
und meldet fehlende Soll-Keys. Eignet sich als CI-Check.
Optionen
--------
--prefix TEXT Collection-Prefix (CLI überschreibt ENV)
--require K [K ...] Zusätzliche Soll-Keys (Default: body|frontmatter|full:parsed:canonical)
--fail-on-missing Exitcode 2, wenn fehlende Keys gefunden werden
Beispiele
---------
python3 -m scripts.report_hashes --prefix mindnet
python3 -m scripts.report_hashes --require frontmatter:raw:none --fail-on-missing
"""
from __future__ import annotations
import argparse
import json
import os
from typing import List, Dict, Any
from qdrant_client.http import models as rest
from app.core.qdrant import QdrantConfig, get_client
def collections(prefix: str):
return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges"
def _scroll_all(client, collection: str):
out = []
nextp = None
while True:
pts, nextp = client.scroll(collection_name=collection, with_payload=True, with_vectors=False, limit=256, offset=nextp)
if not pts:
break
out.extend(pts)
if nextp is None:
break
return out
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--prefix", help="Collection-Prefix (überschreibt ENV COLLECTION_PREFIX)")
ap.add_argument("--require", nargs="+", help="Zusätzliche Soll-Keys <mode>:<source>:<normalize>")
ap.add_argument("--fail-on-missing", action="store_true", help="Exitcode 2 bei fehlenden Keys")
args = ap.parse_args()
cfg = QdrantConfig.from_env()
if args.prefix:
cfg.prefix = args.prefix.strip()
client = get_client(cfg)
notes_col, _, _ = collections(cfg.prefix)
pts = _scroll_all(client, notes_col)
required = set(args.require or [])
required |= {
"body:parsed:canonical",
"frontmatter:parsed:canonical",
"full:parsed:canonical",
}
missing_total = 0
for p in pts:
pl = p.payload or {}
nid = pl.get("note_id")
hashes = pl.get("hashes") or {}
present = set(hashes.keys())
missing = sorted(list(required - present))
obj = {
"note_id": nid,
"present_count": len(present),
"missing": missing,
}
print(json.dumps(obj, ensure_ascii=False))
missing_total += len(missing)
if args.fail_on_missing and missing_total > 0:
raise SystemExit(2)
print(json.dumps({"summary_missing_total": missing_total}))
if __name__ == "__main__":
main()
+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()
+49
View File
@@ -0,0 +1,49 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
tests/audit_edges_now.py — Zählt Edges nach kind & scope und zeigt Chunk- und Note-Anzahl.
"""
import os, sys, json
PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
if PROJECT_ROOT not in sys.path:
sys.path.insert(0, PROJECT_ROOT)
from qdrant_client.http import models as rest
from app.core.qdrant import QdrantConfig, get_client
def scroll_all(c, col, flt=None):
out, nextp = [], None
while True:
pts, nextp = c.scroll(collection_name=col, with_payload=True, with_vectors=False, limit=256, scroll_filter=flt, offset=nextp)
if not pts: break
out.extend(pts)
if nextp is None: break
return out
def main():
cfg = QdrantConfig.from_env()
c = get_client(cfg)
notes = f"{cfg.prefix}_notes"
chunks = f"{cfg.prefix}_chunks"
edges = f"{cfg.prefix}_edges"
es = scroll_all(c, edges)
counts = {}
by_scope = {}
for p in es:
pl = p.payload or {}
k = pl.get("kind") or "?"
s = pl.get("scope") or "?"
counts[k] = counts.get(k, 0) + 1
key = f"{k}:{s}"
by_scope[key] = by_scope.get(key, 0) + 1
print(json.dumps({
"collections": {"notes": notes, "chunks": chunks, "edges": edges},
"total_edges": len(es),
"counts": counts,
"counts_by_scope": by_scope
}, ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
+146
View File
@@ -0,0 +1,146 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
tests/check_chunks_window_vs_text.py
Prüft pro Note und global:
- ob window == text (sollte bei Overlap normalerweise NEIN sein)
- ungefähre linke Overlap-Länge (Suffix von prev.text vs. Prefix von cur.window)
- Größen & einfache Statistiken
Nutzung:
python3 tests/check_chunks_window_vs_text.py --prefix mindnet [--vault ./test_vault]
"""
from __future__ import annotations
import os, sys, json, argparse
from typing import List, Dict, Any, Tuple, Optional
PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
if PROJECT_ROOT not in sys.path:
sys.path.insert(0, PROJECT_ROOT)
from app.core.qdrant import QdrantConfig, get_client
from qdrant_client.http import models as rest
def collections(prefix: str) -> Tuple[str, str, str]:
return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges"
def scroll_chunks_by_note(client, chunks_col: str, note_id: str) -> List[Dict[str, Any]]:
f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
out = []
next_page = None
while True:
pts, next_page = client.scroll(
collection_name=chunks_col,
with_payload=True,
with_vectors=False,
limit=256,
offset=next_page,
scroll_filter=f,
)
if not pts:
break
out.extend([p.payload or {} for p in pts])
if next_page is None:
break
# sortieren: seq -> chunk_index -> chunk_id
def keyer(pl):
return (pl.get("seq", 1<<30), pl.get("chunk_index", 1<<30), str(pl.get("chunk_id", "")))
return sorted(out, key=keyer)
def list_note_ids(client, notes_col: str) -> List[str]:
out = []
next_page = None
while True:
pts, next_page = client.scroll(
collection_name=notes_col,
with_payload=True,
with_vectors=False,
limit=256,
offset=next_page,
)
if not pts:
break
for p in pts:
pl = p.payload or {}
nid = pl.get("note_id")
if isinstance(nid, str):
out.append(nid)
if next_page is None:
break
return sorted(set(out))
def common_overlap_len(a_suffix: str, b_prefix: str, max_probe: int = 256) -> int:
"""
Länge des längsten Suffix von a_suffix, das Prefix von b_prefix ist (bruteforce, begrenzt).
"""
n = min(len(a_suffix), len(b_prefix), max_probe)
if n <= 0:
return 0
a = a_suffix[-n:]
b = b_prefix[:n]
# steigere den Match von 0..n
for k in range(n, 0, -1):
if a[-k:] == b[:k]:
return k
return 0
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--prefix", required=True)
ap.add_argument("--vault", help="optional, nur für Vergleichsausgaben")
args = ap.parse_args()
cfg = QdrantConfig.from_env()
cfg.prefix = args.prefix
client = get_client(cfg)
notes_col, chunks_col, _ = collections(cfg.prefix)
note_ids = list_note_ids(client, notes_col)
if not note_ids:
print(json.dumps({"error": "no notes found in qdrant for this prefix"}))
return
global_total = 0
global_ident = 0
global_left_ov_sum = 0
detail = []
for nid in note_ids:
chunks = scroll_chunks_by_note(client, chunks_col, nid)
if not chunks:
detail.append({"note_id": nid, "chunks": 0})
continue
ident = 0
left_ov_sum = 0
for i, ch in enumerate(chunks):
txt = (ch.get("text") or "").replace("\r\n", "\n")
win = (ch.get("window") or "").replace("\r\n", "\n")
if txt == win:
ident += 1
if i > 0:
prev_txt = (chunks[i-1].get("text") or "").replace("\r\n", "\n")
left_ov = common_overlap_len(prev_txt, win, max_probe=1024)
left_ov_sum += left_ov
global_total += len(chunks)
global_ident += ident
global_left_ov_sum += left_ov_sum
detail.append({
"note_id": nid,
"chunks": len(chunks),
"identical_text_window": ident,
"identical_share": round(ident / max(1, len(chunks)), 3),
"avg_left_overlap_est": round(left_ov_sum / max(1, len(chunks)-1), 2) if len(chunks) > 1 else 0.0
})
out = {
"notes": len(note_ids),
"chunks_total": global_total,
"identical_total": global_ident,
"identical_share_global": round(global_ident / max(1, global_total), 3),
"avg_left_overlap_est_global": round(global_left_ov_sum / max(1, global_total - len(note_ids)), 2) if global_total > len(note_ids) else 0.0,
"details": detail[:100] # capped
}
print(json.dumps(out, ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
+146
View File
@@ -0,0 +1,146 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
tests/check_chunks_window_vs_text.py
Prüft pro Note und global:
- ob window == text (sollte bei Overlap normalerweise NEIN sein)
- ungefähre linke Overlap-Länge (Suffix von prev.text vs. Prefix von cur.window)
- Größen & einfache Statistiken
Nutzung:
python3 tests/check_chunks_window_vs_text.py --prefix mindnet [--vault ./test_vault]
"""
from __future__ import annotations
import os, sys, json, argparse
from typing import List, Dict, Any, Tuple, Optional
PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
if PROJECT_ROOT not in sys.path:
sys.path.insert(0, PROJECT_ROOT)
from app.core.qdrant import QdrantConfig, get_client
from qdrant_client.http import models as rest
def collections(prefix: str) -> Tuple[str, str, str]:
return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges"
def scroll_chunks_by_note(client, chunks_col: str, note_id: str) -> List[Dict[str, Any]]:
f = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=note_id))])
out = []
next_page = None
while True:
pts, next_page = client.scroll(
collection_name=chunks_col,
with_payload=True,
with_vectors=False,
limit=256,
offset=next_page,
scroll_filter=f,
)
if not pts:
break
out.extend([p.payload or {} for p in pts])
if next_page is None:
break
# sortieren: seq -> chunk_index -> chunk_id
def keyer(pl):
return (pl.get("seq", 1<<30), pl.get("chunk_index", 1<<30), str(pl.get("chunk_id", "")))
return sorted(out, key=keyer)
def list_note_ids(client, notes_col: str) -> List[str]:
out = []
next_page = None
while True:
pts, next_page = client.scroll(
collection_name=notes_col,
with_payload=True,
with_vectors=False,
limit=256,
offset=next_page,
)
if not pts:
break
for p in pts:
pl = p.payload or {}
nid = pl.get("note_id")
if isinstance(nid, str):
out.append(nid)
if next_page is None:
break
return sorted(set(out))
def common_overlap_len(a_suffix: str, b_prefix: str, max_probe: int = 256) -> int:
"""
Länge des längsten Suffix von a_suffix, das Prefix von b_prefix ist (bruteforce, begrenzt).
"""
n = min(len(a_suffix), len(b_prefix), max_probe)
if n <= 0:
return 0
a = a_suffix[-n:]
b = b_prefix[:n]
# steigere den Match von 0..n
for k in range(n, 0, -1):
if a[-k:] == b[:k]:
return k
return 0
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--prefix", required=True)
ap.add_argument("--vault", help="optional, nur für Vergleichsausgaben")
args = ap.parse_args()
cfg = QdrantConfig.from_env()
cfg.prefix = args.prefix
client = get_client(cfg)
notes_col, chunks_col, _ = collections(cfg.prefix)
note_ids = list_note_ids(client, notes_col)
if not note_ids:
print(json.dumps({"error": "no notes found in qdrant for this prefix"}))
return
global_total = 0
global_ident = 0
global_left_ov_sum = 0
detail = []
for nid in note_ids:
chunks = scroll_chunks_by_note(client, chunks_col, nid)
if not chunks:
detail.append({"note_id": nid, "chunks": 0})
continue
ident = 0
left_ov_sum = 0
for i, ch in enumerate(chunks):
txt = (ch.get("text") or "").replace("\r\n", "\n")
win = (ch.get("window") or "").replace("\r\n", "\n")
if txt == win:
ident += 1
if i > 0:
prev_txt = (chunks[i-1].get("text") or "").replace("\r\n", "\n")
left_ov = common_overlap_len(prev_txt, win, max_probe=1024)
left_ov_sum += left_ov
global_total += len(chunks)
global_ident += ident
global_left_ov_sum += left_ov_sum
detail.append({
"note_id": nid,
"chunks": len(chunks),
"identical_text_window": ident,
"identical_share": round(ident / max(1, len(chunks)), 3),
"avg_left_overlap_est": round(left_ov_sum / max(1, len(chunks)-1), 2) if len(chunks) > 1 else 0.0
})
out = {
"notes": len(note_ids),
"chunks_total": global_total,
"identical_total": global_ident,
"identical_share_global": round(global_ident / max(1, global_total), 3),
"avg_left_overlap_est_global": round(global_left_ov_sum / max(1, global_total - len(note_ids)), 2) if global_total > len(note_ids) else 0.0,
"details": detail[:100] # capped
}
print(json.dumps(out, ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
+177
View File
@@ -0,0 +1,177 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
tests/compare_vaults.py
Vergleicht zwei Markdown-Vaults rekursiv:
- Schlüsselauswahl: id | title | filename | auto (default: auto = id>title>filename)
- Fokus: body | frontmatter | all (default: body)
- Unicode: NFC-Normalisierung für IDs/Titel/Dateinamen und Text
Beispiele:
python3 tests/compare_vaults.py --src ./vault --dst ./_exportVault --focus body
python3 tests/compare_vaults.py --src ./vault --dst ./_exportVault --key id --focus all
Ausgabe:
- Einträge mit 'missing' (nur in src oder nur in dst)
- Einträge mit 'diff' (vorhanden in beiden, aber Abweichungen gem. Fokus)
- Summary-Objekt am Ende
"""
from __future__ import annotations
import os
import sys
import json
import argparse
import unicodedata
from typing import Dict, Tuple, Optional, Any
PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
if PROJECT_ROOT not in sys.path:
sys.path.insert(0, PROJECT_ROOT)
# Wir nutzen denselben Parser wie im Projekt (fehlertolerant)
from app.core.parser import read_markdown # erwartet: (frontmatter, body)
MD_EXTS = {".md", ".markdown"}
def nfc(s: Optional[str]) -> str:
return unicodedata.normalize("NFC", s or "")
def norm_text(txt: str) -> str:
# normalize line endings + strip trailing spaces per line + NFC
t = txt.replace("\r\n", "\n").replace("\r", "\n")
t = "\n".join(line.rstrip() for line in t.split("\n")).strip()
return nfc(t)
def iter_md_files(root: str):
for base, _dirs, files in os.walk(root):
for fn in files:
ext = os.path.splitext(fn)[1].lower()
if ext in MD_EXTS:
yield os.path.join(base, fn)
def key_from(front: Dict[str, Any], path: str, pref: str) -> str:
"""
Liefert den Vergleichsschlüssel.
pref in {"auto","id","title","filename"}
"""
if pref == "id":
return nfc(str(front.get("id", "")).strip())
if pref == "title":
return nfc(str(front.get("title", "")).strip())
if pref == "filename":
name = os.path.splitext(os.path.basename(path))[0]
return nfc(name.strip())
# auto: id > title > filename
if "id" in front and str(front["id"]).strip():
return nfc(str(front["id"]).strip())
if "title" in front and str(front["title"]).strip():
return nfc(str(front["title"]).strip())
name = os.path.splitext(os.path.basename(path))[0]
return nfc(name.strip())
def load_index(root: str, key_pref: str) -> Dict[str, Tuple[str, Dict[str, Any], str]]:
"""
Baut ein Index-Dict: key -> (path, frontmatter, body)
"""
idx: Dict[str, Tuple[str, Dict[str, Any], str]] = {}
for p in iter_md_files(root):
try:
fm, body = read_markdown(p)
k = key_from(fm or {}, p, key_pref)
if not k:
# Fallback: filename
k = key_from({}, p, "filename")
idx[k] = (p, fm or {}, body or "")
except Exception as e:
# Datei nicht parsebar -> trotzdem indexieren nach Dateiname (leer FM/Body)
k = key_from({}, p, key_pref if key_pref != "auto" else "filename")
idx[k] = (p, {}, "")
return idx
def compare_entries(src: Tuple[str, Dict[str, Any], str],
dst: Tuple[str, Dict[str, Any], str],
focus: str) -> Dict[str, Any]:
sp, sfm, sbody = src
dp, dfm, dbody = dst
res = {"status": "ok"} # wird 'diff' falls Unterschiede
diffs = {}
if focus in ("frontmatter", "all"):
# Vergleiche FM minimal: id und title
s_id = nfc(str(sfm.get("id", "")).strip())
d_id = nfc(str(dfm.get("id", "")).strip())
s_title = nfc(str(sfm.get("title", "")).strip())
d_title = nfc(str(dfm.get("title", "")).strip())
if s_id != d_id:
diffs["frontmatter.id"] = {"src": s_id, "dst": d_id}
if s_title != d_title:
diffs["frontmatter.title"] = {"src": s_title, "dst": d_title}
if focus in ("body", "all"):
if norm_text(sbody) != norm_text(dbody):
diffs["body"] = {"src_len": len(sbody or ""), "dst_len": len(dbody or "")}
if diffs:
res["status"] = "diff"
res["diffs"] = diffs
res["src_path"] = sp
res["dst_path"] = dp
return res
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--src", required=True, help="Quell-Vault-Ordner")
ap.add_argument("--dst", required=True, help="Export-Vault-Ordner")
ap.add_argument("--focus", choices=["body", "frontmatter", "all"], default="body")
ap.add_argument("--key", choices=["auto", "id", "title", "filename"], default="auto",
help="Vergleichsschlüssel (default: auto=id>title>filename)")
args = ap.parse_args()
src_idx = load_index(args.src, args.key)
dst_idx = load_index(args.dst, args.key)
src_keys = set(src_idx.keys())
dst_keys = set(dst_idx.keys())
# Fehlende
only_src = sorted(src_keys - dst_keys)
only_dst = sorted(dst_keys - src_keys)
count = 0
for k in only_src:
print(json.dumps({"note_id": k, "status": "missing", "src": True, "dst": False}, ensure_ascii=False))
count += 1
for k in only_dst:
print(json.dumps({"note_id": k, "status": "missing", "src": False, "dst": True}, ensure_ascii=False))
count += 1
# Vergleiche, wo vorhanden
diff_count = 0
common = sorted(src_keys & dst_keys)
for k in common:
res = compare_entries(src_idx[k], dst_idx[k], args.focus)
if res["status"] == "diff":
res["note_id"] = k
print(json.dumps(res, ensure_ascii=False))
diff_count += 1
summary = {
"summary": "OK" if (count == 0 and diff_count == 0) else "DIFFS",
"missing_count": count,
"diff_count": diff_count,
"total_src": len(src_keys),
"total_dst": len(dst_keys),
"focus": args.focus,
"key": args.key,
}
print(json.dumps(summary, ensure_ascii=False))
# Exit-Code für CI
if summary["summary"] != "OK":
# non-zero exit optional; hier 0 lassen, damit CLI-Ausgaben sichtbar bleiben
pass
if __name__ == "__main__":
main()
+70
View File
@@ -0,0 +1,70 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
tests/inspect_one_note.py
Diagnose einer einzelnen Markdown-Datei (kein Upsert).
Usage:
python3 tests/inspect_one_note.py --path ./test_vault/30_projects/project-demo.md
"""
from __future__ import annotations
import os, sys, json, argparse
PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
if PROJECT_ROOT not in sys.path:
sys.path.insert(0, PROJECT_ROOT)
from app.core.parser import read_markdown, normalize_frontmatter, validate_required_frontmatter
from app.core.chunker import assemble_chunks
from app.core.chunk_payload import make_chunk_payloads
try:
from app.core.derive_edges import build_edges_for_note
except Exception:
from app.core.edges import build_edges_for_note # type: ignore
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--path", required=True)
args = ap.parse_args()
p = os.path.abspath(args.path)
try:
parsed = read_markdown(p)
if parsed is None:
print(json.dumps({"path": p, "error": "read_markdown returned None"}))
return
except Exception as e:
print(json.dumps({"path": p, "error": f"read_markdown failed: {type(e).__name__}: {e}"}))
return
try:
fm = normalize_frontmatter(parsed.frontmatter)
validate_required_frontmatter(fm)
except Exception as e:
print(json.dumps({"path": p, "error": f"frontmatter invalid: {type(e).__name__}: {e}"}))
return
body = getattr(parsed, "body", "") or ""
chunks = assemble_chunks(fm["id"], body, fm.get("type", "concept"))
rel_for_payload = os.path.relpath(p, os.path.join(p, "..", ".."))
chunk_pls = make_chunk_payloads(fm, rel_for_payload, chunks, note_text=body)
edge_error = None
edges_count = 0
try:
edges = build_edges_for_note(fm["id"], chunk_pls, include_note_scope_refs=True)
edges_count = len(edges)
except Exception as e:
edge_error = f"{type(e).__name__}: {e}"
print(json.dumps({
"path": p,
"id": fm.get("id"),
"title": fm.get("title"),
"body_len": len(body),
"chunks": len(chunk_pls),
"edges": edges_count,
"edge_error": edge_error
}, ensure_ascii=False, indent=2))
if __name__ == "__main__":
main()
+49
View File
@@ -0,0 +1,49 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
tests/list_md_seen_by_importer.py
Zeigt, welche Markdown-Dateien der Importer sehen würde (gleiche Filter & Sortierung).
Usage:
python3 tests/list_md_seen_by_importer.py --vault ./test_vault
"""
from __future__ import annotations
import argparse, os, sys, json
def iter_md(root: str):
out = []
for dirpath, _, filenames in os.walk(root):
for fn in filenames:
p = os.path.join(dirpath, fn)
pn = p.replace("\\", "/")
item = {
"path": os.path.abspath(p),
"rel": os.path.relpath(p, root).replace("\\", "/"),
"included": False,
"reason": "",
}
if not fn.lower().endswith(".md"):
item["reason"] = "skip_ext"
elif "/.obsidian/" in pn or "/_backup_frontmatter/" in pn or "/_imported/" in pn:
item["reason"] = "skip_special_dir"
else:
item["included"] = True
item["reason"] = "ok"
out.append(item)
# auch die ausgeschlossenen zeigen:
if not item["included"]:
print(json.dumps(item, ensure_ascii=False))
out_sorted = sorted(out, key=lambda x: x["rel"])
for i, it in enumerate(out_sorted):
it["order"] = i
print(json.dumps(it, ensure_ascii=False))
print(json.dumps({"summary":"done","included":len(out_sorted)}, ensure_ascii=False))
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--vault", required=True)
args = ap.parse_args()
root = os.path.abspath(args.vault)
iter_md(root)
if __name__ == "__main__":
main()
+93
View File
@@ -0,0 +1,93 @@
#!/usr/bin/env bash
set -euo pipefail
# tests/run_e2e_roundtrip.sh
# End-to-End Testpipeline für mindnet WP-03
#
# Schritte:
# 1) Qdrant truncate (Prefix!)
# 2) Import (Apply + Purge) => Create-Fall
# 3) Import (Apply - ohne Änderungen) => Idempotenz
# 4) Hash-Reporter (Fehlende Hash-Varianten)
# 5) Export nach _exportVault
# 6) Vergleich Vault vs. Export (Body-Fokus)
# 7) Sync-Deletes: Eine Datei temporär „entfernen“, Dry-Run + Apply, dann zurückrollen
#
# Aufrufe:
# ./tests/run_e2e_roundtrip.sh [--vault ./test_vault] [--prefix mindnet]
#
# ENV:
# COLLECTION_PREFIX (Default mindnet)
VAULT="./test_vault"
PREFIX="${COLLECTION_PREFIX:-mindnet}"
while [[ $# -gt 0 ]]; do
case "$1" in
--vault) VAULT="$2"; shift 2;;
--prefix) PREFIX="$2"; shift 2;;
*) echo "Unbekannte Option: $1" >&2; exit 2;;
esac
done
echo "== E2E Roundtrip =="
echo "Vault: $VAULT"
echo "Prefix: $PREFIX"
echo
export COLLECTION_PREFIX="$PREFIX"
echo "-- 1) Qdrant truncate"
python3 -m scripts.reset_qdrant --mode truncate --prefix "$PREFIX"
python3 -m scripts.debug_qdrant_state --prefix "$PREFIX"
echo
echo "-- 2) Import (Create-Fall)"
python3 -m scripts.import_markdown --vault "$VAULT" --apply --purge-before-upsert --prefix "$PREFIX"
python3 -m scripts.debug_qdrant_state --prefix "$PREFIX"
echo
echo "-- 3) Import (Idempotenz: keine Änderungen erwartet)"
python3 -m scripts.import_markdown --vault "$VAULT" --apply --prefix "$PREFIX"
python3 -m scripts.debug_qdrant_state --prefix "$PREFIX"
echo
echo "-- 4) Hash-Reporter"
python3 -m scripts.report_hashes --prefix "$PREFIX" || true
echo
echo "-- 5) Export nach _exportVault"
OUT_DIR="_exportVault"
rm -rf "$OUT_DIR"
python3 -m scripts.export_markdown --out "$OUT_DIR" --prefix "$PREFIX"
echo
echo "-- 6) Vergleich Vault vs. Export (Body-Fokus)"
python3 tests/compare_vaults.py --src "$VAULT" --dst "$OUT_DIR" --focus body
echo
echo "-- 7) Sync-Deletes (simuliert)"
# wähle eine Datei und verschiebe sie temporär weg
TMP_DIR="$(mktemp -d)"
SAMPLE_MD="$(find "$VAULT" -type f -name '*.md' | head -n 1 || true)"
if [[ -n "${SAMPLE_MD:-}" ]]; then
mv "$SAMPLE_MD" "$TMP_DIR/"
echo "Temporär entfernt: $(basename "$SAMPLE_MD")"
echo " 7a) Dry-Run"
python3 -m scripts.import_markdown --vault "$VAULT" --sync-deletes --prefix "$PREFIX"
echo " 7b) Apply"
python3 -m scripts.import_markdown --vault "$VAULT" --sync-deletes --apply --prefix "$PREFIX"
# zurückrollen
mv "$TMP_DIR/$(basename "$SAMPLE_MD")" "$SAMPLE_MD"
rm -rf "$TMP_DIR"
echo " 7c) Re-Import (wieder anlegen)"
python3 -m scripts.import_markdown --vault "$VAULT" --apply --prefix "$PREFIX"
python3 -m scripts.debug_qdrant_state --prefix "$PREFIX"
else
echo "Hinweis: Keine MD-Datei im Vault gefunden – Sync-Deletes übersprungen."
fi
echo
echo "== E2E Roundtrip abgeschlossen =="
+105
View File
@@ -0,0 +1,105 @@
#!/usr/bin/env bash
set -euo pipefail
# tests/test_importer_detect_changes.sh
# Prüft Änderungserkennung:
# - Body-Change -> wird erkannt bei hash-mode=body
# - Frontmatter-Change -> wird NICHT erkannt bei hash-mode=body
# - Frontmatter-Change -> wird erkannt bei hash-mode=frontmatter (bzw. MINDNET_HASH_COMPARE=Frontmatter)
#
# Aufruf:
# ./tests/test_importer_detect_changes.sh [--vault ./test_vault] [--prefix mindnet] [--note-id concept-alpha]
VAULT="./test_vault"
PREFIX="${COLLECTION_PREFIX:-mindnet}"
NOTE_ID="concept-alpha"
while [[ $# -gt 0 ]]; do
case "$1" in
--vault) VAULT="$2"; shift 2;;
--prefix) PREFIX="$2"; shift 2;;
--note-id) NOTE_ID="$2"; shift 2;;
*) echo "Unbekannte Option: $1" >&2; exit 2;;
esac
done
export COLLECTION_PREFIX="$PREFIX"
# Hilfsfunktion: lese Pfad zur Note aus Frontmatter id:
PYFIND=$(cat <<'PY'
import sys, os, glob, yaml
vault = sys.argv[1]
nid = sys.argv[2]
for p in glob.glob(os.path.join(vault, "**", "*.md"), recursive=True):
with open(p, "r", encoding="utf-8") as f:
s = f.read()
if s.startswith("---"):
try:
fm_txt, body = s.split("\n---\n", 1)
fm = yaml.safe_load(fm_txt.strip("- \n")) or {}
except Exception:
continue
if fm.get("id") == nid:
print(p)
break
PY
)
NOTE_PATH=$(python3 -c "$PYFIND" "$VAULT" "$NOTE_ID")
if [[ -z "${NOTE_PATH:-}" ]]; then
echo "Note mit id=$NOTE_ID nicht gefunden im Vault=$VAULT" >&2
exit 3
fi
echo "Note: $NOTE_PATH"
# Backup
ORIG="$(mktemp)"
cp "$NOTE_PATH" "$ORIG"
cleanup() {
cp "$ORIG" "$NOTE_PATH" || true
rm -f "$ORIG"
}
trap cleanup EXIT
# Ausgangszustand importieren (Baseline)
python3 -m scripts.import_markdown --vault "$VAULT" --apply --prefix "$PREFIX" >/dev/null
echo "-- Test A: Body-Änderung soll erkannt werden (hash-mode=body)"
# Body um eine Zeile erweitern
python3 - "$NOTE_PATH" <<'PY'
import sys
p=sys.argv[1]
with open(p,"r+",encoding="utf-8") as f:
s=f.read()
if s.startswith("---"):
fm, body = s.split("\n---\n",1)
body = body + "\n\nBodyTest: Änderung A"
f.seek(0); f.truncate(); f.write(fm+"\n---\n"+body)
PY
OUT=$(python3 -m scripts.import_markdown --vault "$VAULT" --prefix "$PREFIX" | grep "\"note_id\": \"$NOTE_ID\"" || true)
echo "$OUT"
echo "$OUT" | grep -q '"changed": true' || { echo "ERWARTET: changed=true (Body) — FEHLER"; exit 4; }
echo "-- Test B: Frontmatter-Änderung soll NICHT erkannt werden bei mode=body"
# Frontmatter-Feld hinzufügen
python3 - "$NOTE_PATH" <<'PY'
import sys, yaml, io
p=sys.argv[1]
with open(p,"r+",encoding="utf-8") as f:
s=f.read()
if s.startswith("---"):
fm_txt, body = s.split("\n---\n",1)
fm = yaml.safe_load(fm_txt.strip("- \n")) or {}
fm["test_flag"] = True
buf = io.StringIO()
yaml.safe_dump(fm, buf, allow_unicode=True, sort_keys=False)
f.seek(0); f.truncate(); f.write("---\n"+buf.getvalue()+"---\n"+body)
PY
OUT=$(python3 -m scripts.import_markdown --vault "$VAULT" --prefix "$PREFIX" | grep "\"note_id\": \"$NOTE_ID\"" || true)
echo "$OUT"
echo "$OUT" | grep -q '"changed": false' || { echo "ERWARTET: changed=false (FM bei mode=body) — FEHLER"; exit 5; }
echo "-- Test C: Frontmatter-Änderung soll erkannt werden bei mode=frontmatter"
OUT=$(MINDNET_HASH_COMPARE=Frontmatter python3 -m scripts.import_markdown --vault "$VAULT" --prefix "$PREFIX" | grep "\"note_id\": \"$NOTE_ID\"" || true)
echo "$OUT"
echo "$OUT" | grep -q '"changed": true' || { echo "ERWARTET: changed=true (FM bei mode=frontmatter) — FEHLER"; exit 6; }
echo "✔ Änderungserkennung: OK"
+193
View File
@@ -0,0 +1,193 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Script: tests/verify_chunks_integrity.py
Version: 1.0.1
Datum: 2025-09-10
Zweck
-----
Verifiziert die Text-Integrität der gespeicherten Chunks:
1) Rekonstruiert den Body aus den Chunks (Sortierung: seq → chunk_index → # in chunk_id).
2) Vergleicht mit dem in Qdrant gespeicherten Note-`fulltext` (falls vorhanden).
3) Optional: Vergleicht zusätzlich mit dem Body der zugehörigen Markdown-Datei im Vault.
Aufrufe
-------
# Nur gegen Qdrant (fulltext vs. Chunks)
python3 tests/verify_chunks_integrity.py --prefix mindnet
# Zusätzlich gegen den Vault abgleichen (Body der .md-Datei)
python3 tests/verify_chunks_integrity.py --prefix mindnet --vault ./test_vault
# Streng + CI-geeignet (Fehlercode bei Abweichungen):
python3 tests/verify_chunks_integrity.py --prefix mindnet --vault ./test_vault --strict --fail-on-mismatch
"""
from __future__ import annotations
import argparse
import json
import os
import sys
from typing import Any, Dict, List, Optional, Tuple
# --- FIX: Projekt-Root in sys.path aufnehmen, damit 'app.*' importierbar ist ---
PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
if PROJECT_ROOT not in sys.path:
sys.path.insert(0, PROJECT_ROOT)
import yaml
from qdrant_client.http import models as rest
from app.core.qdrant import QdrantConfig, get_client
# --------------------------- Helpers ---------------------------
def collections(prefix: str) -> Tuple[str, str, str]:
return f"{prefix}_notes", f"{prefix}_chunks", f"{prefix}_edges"
def scroll_all(client, collection: str, flt: Optional[rest.Filter] = None, limit: int = 256) -> List[Any]:
out: List[Any] = []
nextp = None
while True:
pts, nextp = client.scroll(
collection_name=collection,
with_payload=True,
with_vectors=False,
limit=limit,
offset=nextp,
scroll_filter=flt,
)
if not pts:
break
out.extend(pts)
if nextp is None:
break
return out
def sort_key_for_chunk_payload(pl: Dict[str, Any]) -> Tuple[int, int, int]:
s = pl.get("seq") or 0
ci = pl.get("chunk_index") or 0
n = 0
cid = pl.get("chunk_id") or ""
if isinstance(cid, str) and "#" in cid:
try:
n = int(cid.rsplit("#", 1)[-1])
except Exception:
n = 0
return (int(s), int(ci), int(n))
def reconstruct_from_chunks(chunks_points: List[Any]) -> Tuple[str, int, int]:
"""Gibt (text, total_chunks, chunks_with_text) zurück."""
chunks_sorted = sorted(chunks_points, key=lambda p: sort_key_for_chunk_payload(p.payload or {}))
texts: List[str] = []
have = 0
for p in chunks_sorted:
pl = p.payload or {}
t = pl.get("text") or pl.get("content") or pl.get("raw") or ""
if isinstance(t, str) and t:
have += 1
texts.append(t)
return ("\n".join(texts).strip(), len(chunks_sorted), have)
def normalize(s: str, strict: bool = False) -> str:
if s is None:
return ""
s = s.replace("\r\n", "\n").replace("\r", "\n")
if strict:
return s
lines = [ln.rstrip() for ln in s.strip().split("\n")]
return "\n".join(lines).strip()
def read_vault_body(vault_root: str, rel_path: str) -> Optional[str]:
if not rel_path:
return None
p = os.path.join(vault_root, rel_path.replace("\\", "/").lstrip("/"))
if not os.path.exists(p):
return None
with open(p, "r", encoding="utf-8") as f:
s = f.read()
if s.startswith("---"):
try:
fm_txt, body = s.split("\n---\n", 1)
except Exception:
return s
else:
body = s
return body
# --------------------------- Main ------------------------------
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--prefix", help="Collection-Prefix (überschreibt ENV COLLECTION_PREFIX)")
ap.add_argument("--vault", help="Optional: Vault-Wurzelordner für Abgleich gegen .md")
ap.add_argument("--strict", action="store_true", help="Strikter Vergleich (kein Trimmen/Normalisieren)")
ap.add_argument("--fail-on-mismatch", action="store_true", help="Exit 1, wenn ein Mismatch gefunden wurde")
args = ap.parse_args()
cfg = QdrantConfig.from_env()
if args.prefix:
cfg.prefix = args.prefix.strip()
client = get_client(cfg)
notes_col, chunks_col, _ = collections(cfg.prefix)
notes = scroll_all(client, notes_col)
mismatches = 0
total = 0
for n in notes:
total += 1
pl = n.payload or {}
nid = pl.get("note_id")
rel_path = (pl.get("path") or "").replace("\\", "/").lstrip("/")
fulltext = (pl.get("fulltext") or "").strip()
flt = rest.Filter(must=[rest.FieldCondition(key="note_id", match=rest.MatchValue(value=nid))])
chunks = scroll_all(client, chunks_col, flt)
recon, cnt, have = reconstruct_from_chunks(chunks)
norm_recon = normalize(recon, strict=args.strict)
norm_full = normalize(fulltext, strict=args.strict)
match_full = (bool(norm_full) and (norm_recon == norm_full))
match_vault = None
issues: List[str] = []
if cnt == 0:
issues.append("no_chunks")
if have < cnt:
issues.append(f"missing_text_in_chunks:{cnt-have}/{cnt}")
if norm_full == "":
issues.append("note_fulltext_empty")
if not match_full:
issues.append("reconstructed_vs_fulltext_mismatch")
if args.vault:
body = read_vault_body(args.vault, rel_path) or ""
norm_body = normalize(body, strict=args.strict)
match_vault = (norm_body == norm_recon)
if not match_vault:
issues.append("reconstructed_vs_vault_body_mismatch")
obj = {
"note_id": nid,
"path": rel_path,
"chunks_count": cnt,
"chunks_with_text": have,
"match_fulltext": match_full,
"match_vault": match_vault,
"issues": issues,
}
print(json.dumps(obj, ensure_ascii=False))
if ("reconstructed_vs_fulltext_mismatch" in issues) or ("reconstructed_vs_vault_body_mismatch" in issues):
mismatches += 1
summary = {"summary": "OK" if mismatches == 0 else "DIFFS", "mismatch_count": mismatches, "notes": total}
print(json.dumps(summary, ensure_ascii=False))
if args.fail_on_mismatch and mismatches:
raise SystemExit(1)
if __name__ == "__main__":
main()