mindnet/app/core/derive_edges.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Modul: app/core/derive_edges.py
Version: 1.3.0
Datum: 2025-09-30

Zweck
-----
Robuste Kantenbildung für mindnet (Notes/Chunks):
- belongs_to (chunk -> note)
- next / prev (chunk-Kette)
- references (chunk-scope) aus Chunk.window (Fallback text/content/raw)
- optional references (note-scope) dedupliziert
- optional backlink (note-scope) als Gegenkante

Designhinweise
--------------
- Für die Referenz-Extraktion wird bewusst das Feld **window** verwendet (nicht 'text'),
  damit Links, die an einer Overlap-Grenze liegen, nicht verloren gehen.
- IDs werden später deterministisch in app/core/qdrant_points.py aus Payload erzeugt.
- 'status' setzen wir nicht hart; ein separater Resolver kann 'unresolved' o.ä. bestimmen.

Erwartete Chunk-Payload-Felder (pro Element):
    {
      "note_id": "...",
      "chunk_id": "...",    # Alias "id" sollte ebenfalls vorhanden sein (abwärtskompatibel)
      "id": "...",
      "chunk_index": int,
      "seq": int,
      "window": str,
      "text": str,
      "path": "rel/path.md",
      ...
    }

API
---
def build_edges_for_note(
    note_id: str,
    chunks: List[dict],
    note_level_references: List[str] | None = None,
    include_note_scope_refs: bool = False,
) -> List[dict]
"""
from __future__ import annotations

import re
from typing import Dict, List, Optional, Iterable, Tuple

_WIKILINK_RE = re.compile(r"\[\[([^\]]+)\]\]")

def _get(d: dict, *keys, default=None):
    for k in keys:
        if k in d and d[k] is not None:
            return d[k]
    return default

def _chunk_text_for_refs(chunk: dict) -> str:
    # bevorzugt 'window' → dann 'text' → 'content' → 'raw'
    return (
        _get(chunk, "window")
        or _get(chunk, "text")
        or _get(chunk, "content")
        or _get(chunk, "raw")
        or ""
    )

def _extract_wikilinks(text: str) -> List[str]:
    if not text:
        return []
    out: List[str] = []
    for m in _WIKILINK_RE.finditer(text):
        label = m.group(1).strip()
        if not label:
            continue
        # Einfach-Normalisierung: Leerraum trimmen; weitere Normalisierung (Slugging)
        # kann upstream erfolgen (Parser oder Resolver).
        out.append(label)
    return out

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,     # Quelle/Träger der Kante (die 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

    Rückgabe: Liste von Edge-Payloads (ohne 'id'; Qdrant-ID wird deterministisch aus Payload erzeugt)
    """
    edges: List[dict] = []

    # --- Strukturkanten ---
    # belongs_to
    for ch in chunks:
        cid = _get(ch, "chunk_id", "id")
        if not cid:
            # defensiv: überspringen statt Crash
            continue
        edges.append(_edge("belongs_to", "chunk", cid, note_id, note_id, {"chunk_id": cid}))

    # next/prev
    for i in range(len(chunks) - 1):
        a = chunks[i]
        b = chunks[i + 1]
        a_id = _get(a, "chunk_id", "id")
        b_id = _get(b, "chunk_id", "id")
        if not a_id or not b_id:
            continue
        edges.append(_edge("next", "chunk", a_id, b_id, note_id, {"chunk_id": a_id}))
        edges.append(_edge("prev", "chunk", b_id, a_id, note_id, {"chunk_id": b_id}))

    # --- Referenzkanten (chunk-scope) ---
    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)
        if not refs:
            continue
        for r in refs:
            edges.append(_edge("references", "chunk", cid, r, note_id, {"chunk_id": cid, "ref_text": r}))
        refs_all.extend(refs)

    # --- Note-scope (optional) ---
    if include_note_scope_refs:
        # Inputs: dedup aller Chunk-Funde + optional vorhandene Note-Level-Refs aus Payload
        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:
            # forward
            edges.append(_edge("references", "note", note_id, r, note_id))
            # backlink (reverse)
            edges.append(_edge("backlink", "note", r, note_id, note_id))

    return edges