diff --git a/docs/mindnet_v2_implementation_playbook.md b/docs/mindnet_v2_implementation_playbook.md index ae861f7..0fb0637 100644 --- a/docs/mindnet_v2_implementation_playbook.md +++ b/docs/mindnet_v2_implementation_playbook.md @@ -19,6 +19,31 @@ > **Warum so?** Qdrant‑Payload‑Indizes/Filter → schnelle, erklärbare Selektionen; Snapshots → betriebssicheres Rollback; OTel → Nachvollziehbarkeit; YAML/JSON‑Schema → Validierbarkeit & Stabilität. +### 0.1 Aktueller Implementierungsstand (2025-11-18) + +- Es existiert eine produktive mindnet-Instanz mit den Collections: + - `${prefix}_notes` + - `${prefix}_chunks` + - `${prefix}_edges` +- Import-Pipeline: + - `scripts/import_markdown.py` erzeugt Notes, Chunks und Edges vollständig. + - `types.yaml` definiert per Note-Typ: + - `retriever_weight` + - `chunk_profile` + - `edge_defaults` (z. B. `depends_on`, `related_to`). +- Edges: + - Strukturkanten: `belongs_to`, `next`, `prev` + - Explizite Kanten aus Wikilinks: `kind="references"`, `rule_id="explicit:wikilink"` + - Typbasierte Default-Kanten aus `edge_defaults`: `rule_id="edge_defaults::"` + - Inline-Kanten im Format `[[rel: ]]` mit `rule_id="inline:rel"` + - alle Edges tragen eine `confidence` im Bereich `[0,1]` als Hinweis für spätere Ranking-Logiken. +- Tests: + - `tests/test_edges_smoke.py`, `tests/test_edges_all.py` und `scripts/edges_full_check.py` validieren Counts, Konsistenz (`belongs_to == chunks`, `next/prev`-Ketten, keine Duplikate) und Provenienz-Zählungen (`explicit`, `defaults`, `inline`, `structure`). +- Offene Punkte: + - Mehrere Ziele in einer Inline-Relation (`rel: similar_to [[A]] [[B]]`) sind noch nicht implementiert. + - Retrieval-Service nutzt die neuen Edges und Weights bisher nur teilweise; ein edge-bewusster Retriever ist als nächster Schritt geplant. + + --- ## 1) Datenmodelle (Schemata, v2) @@ -196,10 +221,15 @@ rule_sets: - CI‑Job: `make schema-validate` (jsonschema). - **Abnahme:** Validator grün auf 3 Gold‑Notizen. -### Step 2 – Qdrant v2‑Collections +### Step 2 – Qdrant v2‑Collections (Optional) - Anlegen der 3 v2‑Collections + Payload‑Indizes. - **Abnahme:** Filter‑Query liefert erwartbare Ergebnisse. +### Step 2a – Edge-Pipeline v1 stabilisieren (ERLEDIGT) +- Ziel: Vollständige Generierung von Struktur-, expliziten, typbasierten und Inline-Kanten in den bestehenden Collections `${prefix}_notes`, `${prefix}_chunks`, `${prefix}_edges`. +- Status: Implementiert und durch `tests/test_edges_smoke.py`, `tests/test_edges_all.py` und `scripts/edges_full_check.py` verifiziert. + + ### Step 3 – Chunker v2 - Implementierung & Flag `--chunker v2`. - **Abnahme:** Chunk‑Counts ~ alt (≈171 ± 15 %), semantische Schnitte. @@ -208,6 +238,17 @@ rule_sets: - Reihenfolge & `provenance` strikt umsetzen, `default_resolved` integrieren. - **Abnahme:** erwartete Relationensätze auf Gold‑Notizen, keine Duplikate. +### Step 4a – Edge-bewusster Retriever +- Implementiere einen Retrieval-Service, der: + - Chunks über Vektor-Suche aus `${prefix}_chunks` holt, + - dazu passende Nachbar-Chunks (`next/prev`) und typrelevante Notizen (`edge_defaults`, Inline-Relationen, Wikilinks) über `${prefix}_edges` ergänzt, + - `retriever_weight` und `confidence` beim Scoring berücksichtigt. +- Liefere einen API-Endpoint `/mindnet/query` mit einem einfachen JSON-Response (Chunks + Begründung). +- Akzeptanz: + - mindestens ein Testfall mit dem Relations-Showcase-Vault, + - sichtbarer Einfluss von `edge_defaults` und Inline-Relationen auf die Ergebnisliste. + + ### Step 5 – Importer‑Pipeline v2 - `--schema v2` Side‑by‑Side; Batch‑Upserts; vollständige Payloads; Recency‑Boost Konfig **nur** in Policy. - **Abnahme:** Dry‑Run/Apply‑Parität, Reports, Telemetrie‑Ereignisse sichtbar.