366 lines
17 KiB
Markdown
366 lines
17 KiB
Markdown
# mindnet v2 – Implementierungs-Playbook & Handover (Side‑by‑Side zu v1)
|
||
*Stand:* 2025-11-10 08:03
|
||
*Autor:* ChatGPT (Projekt‑Handover)
|
||
*Zweck:* Vollständige, ausführbare Anleitung zur Weiterentwicklung von **mindnet** auf eine versionierte, testbare v2‑Architektur (neben v1), inklusive Prompt für den Folgethread, Akzeptanzkriterien, Dateiliste, Test‑ und Rollback‑Pläne.
|
||
|
||
---
|
||
|
||
## 0) Kontext & Zielbild (kurz)
|
||
- **Mission:** Persönliches Wissensnetz, das langfristig die eigene Persönlichkeit, Erfahrungen und Entscheidungslogik abbildet; später nachvollziehbare Erklärungen für Familie/Nachwelt.
|
||
- **Heutiger Stand (v1):** `mindnet_notes` in Qdrant vorhanden; **Chunks** und **Edges** bisher nur teilweise/nicht konsistent; Edge‑Defaults („1 Dot“) vorhanden, aber Ziele teils nicht materialisiert. Importskripte: `import_markdown.py`, `edges.py` (historisch).
|
||
- **Ziel (v2):**
|
||
- **Collections:** `mindnet_notes_v2`, `mindnet_chunks_v2`, `mindnet_edges_v2` (saubere Payload‑Schemata + Indizes).
|
||
- **Chunker v2:** Block/Heading‑aware, Ziel 900–1200 Zeichen, Überlappung 120–180, deterministische `chunk_id`s.
|
||
- **Edge‑Builder v2:** Reihenfolge: **explicit → rule → default_resolved → default**; saubere `provenance`.
|
||
- **Importer‑Pipeline v2:** Parse → Chunk → Edge → Embeddings → Batch‑Upsert + Payload‑Indexpflege + Snapshots.
|
||
- **Policies:** Privacy/Recency/Type‑Gewichte als **Konfiguration** (YAML + JSON‑Schema), nicht hart im Code.
|
||
- **Observability:** FastAPI + OpenTelemetry (Tracing/Metrics); Import‑Reports (CSV/JSON).
|
||
- **Side‑by‑Side:** v2 **parallel** zu v1; kein Big‑Bang.
|
||
|
||
> **Warum so?** Qdrant‑Payload‑Indizes/Filter → schnelle, erklärbare Selektionen; Snapshots → betriebssicheres Rollback; OTel → Nachvollziehbarkeit; YAML/JSON‑Schema → Validierbarkeit & Stabilität.
|
||
|
||
### 0.1 Aktueller Implementierungsstand (2025-11-18)
|
||
|
||
- Es existiert eine produktive mindnet-Instanz mit den Collections:
|
||
- `${prefix}_notes`
|
||
- `${prefix}_chunks`
|
||
- `${prefix}_edges`
|
||
- Import-Pipeline:
|
||
- `scripts/import_markdown.py` erzeugt Notes, Chunks und Edges vollständig.
|
||
- `types.yaml` definiert per Note-Typ:
|
||
- `retriever_weight`
|
||
- `chunk_profile`
|
||
- `edge_defaults` (z. B. `depends_on`, `related_to`).
|
||
- Edges:
|
||
- Strukturkanten: `belongs_to`, `next`, `prev`
|
||
- Explizite Kanten aus Wikilinks: `kind="references"`, `rule_id="explicit:wikilink"`
|
||
- Typbasierte Default-Kanten aus `edge_defaults`: `rule_id="edge_defaults:<type>:<relation>"`
|
||
- Inline-Kanten im Format `[[rel:<relation> <Zielnote>]]` mit `rule_id="inline:rel"`
|
||
- alle Edges tragen eine `confidence` im Bereich `[0,1]` als Hinweis für spätere Ranking-Logiken.
|
||
- Tests:
|
||
- `tests/test_edges_smoke.py`, `tests/test_edges_all.py` und `scripts/edges_full_check.py` validieren Counts, Konsistenz (`belongs_to == chunks`, `next/prev`-Ketten, keine Duplikate) und Provenienz-Zählungen (`explicit`, `defaults`, `inline`, `structure`).
|
||
- Offene Punkte:
|
||
- Mehrere Ziele in einer Inline-Relation (`rel: similar_to [[A]] [[B]]`) sind noch nicht implementiert.
|
||
- Retrieval-Service nutzt die neuen Edges und Weights bisher nur teilweise; ein edge-bewusster Retriever ist als nächster Schritt geplant.
|
||
|
||
|
||
---
|
||
|
||
## 1) Datenmodelle (Schemata, v2)
|
||
Die tatsächlichen JSON‑Schemata (2020‑12) werden im Repo abgelegt und in CI validiert.
|
||
|
||
### 1.1 note.schema.json
|
||
```json
|
||
{
|
||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||
"$id": "https://example.org/mindnet/note.schema.json",
|
||
"type": "object",
|
||
"required": ["id", "title", "type", "privacy", "created", "hash_body"],
|
||
"properties": {
|
||
"id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$" },
|
||
"title": { "type": "string", "minLength": 1 },
|
||
"type": { "type": "string" },
|
||
"privacy": { "type": "string", "enum": ["public","internal","private"] },
|
||
"created": { "type": "string", "format": "date-time" },
|
||
"modified": { "type": "string", "format": "date-time" },
|
||
"tags": { "type": "array", "items": { "type": "string" } },
|
||
"lang": { "type": "string", "default": "de" },
|
||
"source_path": { "type": "string" },
|
||
"source_collection": { "type": "string" },
|
||
"hash_body": { "type": "string" },
|
||
"hash_frontmatter": { "type": "string" },
|
||
"token_count": { "type": "integer", "minimum": 0 }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.2 chunk.schema.json
|
||
```json
|
||
{
|
||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||
"$id": "https://example.org/mindnet/chunk.schema.json",
|
||
"type": "object",
|
||
"required": ["chunk_id","note_id","text","ord"],
|
||
"properties": {
|
||
"chunk_id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+#c\d{4}$" },
|
||
"note_id": { "type": "string" },
|
||
"text": { "type": "string" },
|
||
"ord": { "type": "integer", "minimum": 0 },
|
||
"span_char_start": { "type": "integer", "minimum": 0 },
|
||
"span_char_end": { "type": "integer", "minimum": 0 },
|
||
"heading_path": { "type": "array", "items": { "type": "string" } },
|
||
"section_title": { "type": "string" },
|
||
"tokens_start": { "type": "integer", "minimum": 0 },
|
||
"tokens_end": { "type": "integer", "minimum": 0 },
|
||
"embeddings_version": { "type": "string" }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.3 edge.schema.json
|
||
```json
|
||
{
|
||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||
"$id": "https://example.org/mindnet/edge.schema.json",
|
||
"type": "object",
|
||
"required": ["edge_id","src_note_id","relation","provenance"],
|
||
"properties": {
|
||
"edge_id": { "type": "string" },
|
||
"src_note_id": { "type": "string" },
|
||
"src_chunk_id": { "type": "string" },
|
||
"dst_note_id": { "type": "string" },
|
||
"dst_chunk_id": { "type": "string" },
|
||
"relation": { "type": "string" },
|
||
"evidence_spans":{ "type": "array", "items": {"type":"object","properties":{"chunk_id":{"type":"string"},"span":[{"type":"integer"},{"type":"integer"}]]} },
|
||
"provenance": { "type": "string", "enum": ["explicit","rule","default_resolved","default"] },
|
||
"rule_id": { "type": "string" },
|
||
"confidence": { "type": "number", "minimum": 0, "maximum": 1 }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.4 default_edge.schema.json
|
||
```json
|
||
{
|
||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||
"$id": "https://example.org/mindnet/default_edge.schema.json",
|
||
"type": "object",
|
||
"required": ["src_note_id","relation","target_kind"],
|
||
"properties": {
|
||
"src_note_id": { "type": "string" },
|
||
"relation": { "type": "string" },
|
||
"target_kind": { "type": "string" },
|
||
"when": { "type": "string" },
|
||
"strength_hint":{ "type": "number", "minimum": 0, "maximum": 1 }
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2) Qdrant: Collections & Indizes (v2)
|
||
Anlegen **neben** v1:
|
||
- `mindnet_notes_v2` (Payload‑Index: `type, privacy, created, modified, tags, source_path`)
|
||
- `mindnet_chunks_v2` (Payload‑Index: `note_id, ord, heading_path`)
|
||
- `mindnet_edges_v2` (Payload‑Index: `src_note_id, dst_note_id, relation, provenance`)
|
||
|
||
> Snapshots für Backups/Restore einplanen (Runbook siehe unten).
|
||
|
||
---
|
||
|
||
## 3) Import‑Pipeline v2 – Module & Flags
|
||
- **Chunker v2** (`chunking/block_chunker.py`): `target_len=1000`, `overlap=150`, `respect_headings=True`, `min_chunk_len=600`, `max_chunk_len=1400`, `chunk_id = f\"{note_id}#c{ordinal:04d}\"`
|
||
- **Edge‑Builder v2** (`graph/edge_builder_v2.py`): Reihenfolge **explicit → rule → default_resolved → default**, `provenance` korrekt setzen.
|
||
- **Importer** (`scripts/import_markdown.py` erweitern oder `scripts/import_markdown_v2.py`):
|
||
Flags: `--schema v2`, `--chunker v2`, `--edges v2`, `--dry-run`, `--apply`, `--prefix "$COLLECTION_PREFIX"`.
|
||
|
||
**Beispiel‑Run (dry‑run):**
|
||
```bash
|
||
python3 -m scripts.import_markdown_v2 --vault ./vault --schema v2 --chunker v2 --edges v2 --dry-run --prefix "$COLLECTION_PREFIX"
|
||
```
|
||
|
||
**Apply:**
|
||
```bash
|
||
python3 -m scripts.import_markdown_v2 --vault ./vault --schema v2 --chunker v2 --edges v2 --apply --prefix "$COLLECTION_PREFIX"
|
||
```
|
||
|
||
---
|
||
|
||
## 4) Policies (konfigurierbar, kein Hard‑Code)
|
||
- `policies/retrieval.schema.json` (JSON‑Schema) und `policies/retrieval.yaml`, z. B.:
|
||
```yaml
|
||
privacy_order: [private, internal, public]
|
||
recency_boost_half_life_days: 90
|
||
type_priority:
|
||
person: 1.2
|
||
event: 1.1
|
||
concept: 1.0
|
||
max_chunks_per_note: 8
|
||
edge_provenance_weights:
|
||
explicit: 1.0
|
||
rule: 0.8
|
||
default_resolved: 0.6
|
||
default: 0.2
|
||
rule_sets:
|
||
- id: "rules:types-v1"
|
||
enabled: true
|
||
```
|
||
|
||
---
|
||
|
||
## 5) Observability & Reports
|
||
- **FastAPI + OpenTelemetry**: Traces um Phasen *parse/chunk/edge/upsert*; Metriken (Counter/Histogramme) pro Phase.
|
||
- **Import‑Report** je Lauf (CSV/JSON): counts für Notes/Chunks/Edges, Fehler, Dauer, Embedding‑Version.
|
||
|
||
---
|
||
|
||
## 6) Teststrategie
|
||
- **Gold‑Notizen** (3–5 repräsentative .md) mit erwarteten *Chunk‑Counts* und *Edge‑Sets*.
|
||
- **Regression:** fixer Soll‑Count (z. B. 171 ± 15 %) über Gesamt‑Vault; keine Duplikate `(src,relation,dst)`.
|
||
- **Dry‑Run vs Apply**: identische Counts, nur ohne Upserts.
|
||
- **Filter‑Smoke‑Tests:** Qdrant‑Filter nach `privacy`, `type`, `tags`, `created` funktionieren performant.
|
||
|
||
---
|
||
|
||
## 7) Akzeptanzkriterien (KPI)
|
||
1. **Chunk‑Qualität:** ≥ 90 % der Chunks enden an semantischen Grenzen; Ziel‑Länge 900–1200 Zeichen; deterministische IDs.
|
||
2. **Edge‑Kohärenz:** Keine Duplikate gleicher `(src,relation,dst)`; ≥ 95 % der expliziten Links materialisiert; `default` nur, wenn kein Ziel existiert.
|
||
3. **Filterbarkeit:** Queries nach `privacy/type/tags/created` performant (Payload‑Index vorhanden).
|
||
4. **Betriebsfestigkeit:** Telemetrie aktiv; fehlertoleranter Import; Qdrant‑Snapshot nach erfolgreichem Lauf.
|
||
|
||
---
|
||
|
||
## 8) Roadmap in kleinen, testbaren Schritten
|
||
|
||
### Step 0 – Safeguards
|
||
- Qdrant‑Snapshot v1 erstellen + Restore‑Probe.
|
||
- ENV: `MINDNET_SCHEMA_VERSION=2` (Importer wird v2 schreiben, v1 bleibt unberührt).
|
||
|
||
### Step 1 – Schemata (nur Dateien)
|
||
- Ablage: `/schemas/note.schema.json`, `/schemas/chunk.schema.json`, `/schemas/edge.schema.json`, `/schemas/default_edge.schema.json`
|
||
- CI‑Job: `make schema-validate` (jsonschema).
|
||
- **Abnahme:** Validator grün auf 3 Gold‑Notizen.
|
||
|
||
### 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.
|
||
|
||
### Step 4 – Edge‑Builder v2
|
||
- 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.
|
||
|
||
### Step 6 – Observability
|
||
- OTel‑Instrumentierung + `/import/status` + Reports.
|
||
- **Abnahme:** Traces & Metriken vorhanden.
|
||
|
||
### Step 7 – Snapshots & Runbook
|
||
- Snapshot nach Erfolg; Restore‑Dokument.
|
||
- **Abnahme:** Restore‑Probe erfolgreich.
|
||
|
||
### Step 8 – Policies
|
||
- `policies/retrieval.yaml` + JSON‑Schema; A/B‑Test (Policy ändern → Retrieval ändert sich ohne Reimport).
|
||
- **Abnahme:** Sichtbarer Effekt laut Testfall.
|
||
|
||
### Step 9 – Umschalten
|
||
- Abnahme‑Doku, KPI‑Delta dokumentiert; Alias/Flag‑Switch auf v2.
|
||
- **Abnahme:** Funktionale Gleichwertigkeit + Qualitätsgewinn.
|
||
|
||
---
|
||
|
||
## 9) Dateien (neu/ändern)
|
||
**Neu:**
|
||
- `schemas/note.schema.json`
|
||
- `schemas/chunk.schema.json`
|
||
- `schemas/edge.schema.json`
|
||
- `schemas/default_edge.schema.json`
|
||
- `policies/retrieval.schema.json`
|
||
- `policies/retrieval.yaml`
|
||
- `chunking/block_chunker.py`
|
||
- `graph/edge_builder_v2.py`
|
||
- `docs/OPERATIONS.md` (Snapshots/Restore/Runbook)
|
||
- `tests/gold_notes/manifest.yaml` (+ 3–5 Notizen Kopien)
|
||
|
||
**Änderungen:**
|
||
- `scripts/import_markdown.py` **oder** `scripts/import_markdown_v2.py` neu (Flags `--schema/--chunker/--edges`).
|
||
- `edges.py` (falls weiterverwendet): auf **v2‑Edge‑Builder** migrieren oder auslaufen lassen.
|
||
- `types.yaml`: Regel‑Definitionen klarisieren (IDs, Bedingungen), **nicht** hart in Code.
|
||
|
||
---
|
||
|
||
## 10) Beispiel‑Kommandos
|
||
```bash
|
||
# Step 2: Collections prüfen
|
||
curl -s http://127.0.0.1:6333/collections | jq
|
||
|
||
# Step 3: Chunker v2 (dry-run)
|
||
python3 -m scripts.import_markdown_v2 --vault ./vault --schema v2 --chunker v2 --edges v2 --dry-run --prefix "$COLLECTION_PREFIX"
|
||
|
||
# Step 5: Apply + Report
|
||
python3 -m scripts.import_markdown_v2 --vault ./vault --schema v2 --chunker v2 --edges v2 --apply --prefix "$COLLECTION_PREFIX" --report ./reports/import_$(date +%F_%H%M).json
|
||
```
|
||
|
||
---
|
||
|
||
## 11) Rollback
|
||
- v2‑Collections droppen (wenn Side‑by‑Side).
|
||
- Aus Snapshot wiederherstellen (v1).
|
||
- Flags zurück auf v1.
|
||
|
||
---
|
||
|
||
## 12) Referenzen (offizielle Quellen)
|
||
- Qdrant – Collections, Payload‑Index, Filter: <https://qdrant.tech/documentation/>
|
||
- Qdrant – Snapshots/Backup: <https://qdrant.tech/documentation/guides/backup/>
|
||
- OpenTelemetry (Python/FastAPI): <https://opentelemetry.io/docs/instrumentation/python/>
|
||
- JSON‑Schema 2020‑12: <https://json-schema.org/>
|
||
- YAML 1.2: <https://yaml.org/spec/1.2.2/>
|
||
- Obsidian Frontmatter: <https://help.obsidian.md/Editing+and+formatting/Properties>
|
||
- Ollama CLI/API (lokale Modelle): <https://github.com/ollama/ollama>
|
||
|
||
---
|
||
|
||
## 13) **PROMPT für den neuen Chat (bitte exakt so einfügen)**
|
||
```
|
||
Rolle: Du bist mein Senior‑Entwickler & Architekt für mindnet. Arbeite strikt in kleinen, testbaren Schritten (Side‑by‑Side v2 neben v1). Liefere komplette Dateien als Downloads. Frage immer zuerst nach den **aktuellsten** Projektdateien, wenn du sie brauchst (z. B. import_markdown.py, edges.py, types.yaml), ändere keine Systemfunktion „workaround‑artig“ ohne die Gesamtwirkung zu prüfen.
|
||
|
||
Kontext (Kurzfassung):
|
||
- v1 hat nur mindnet_notes zuverlässig. Chunks/Edges sind inkonsistent/teilweise leer. Ziel: v2 mit drei Collections (notes/chunks/edges), neuem Chunker v2, Edge‑Builder v2 (explicit → rule → default_resolved → default), Policies (YAML), Observability (OTel), Snapshots. Kein Big‑Bang; v2 parallel zu v1.
|
||
- Siehe angehängte Datei **mindnet_v2_implementation_playbook.md** (Pfad/Download im Chat). Alles daraus ist verbindlich.
|
||
|
||
Deine ersten Aufgaben (Step‑by‑Step):
|
||
1) **Schemata anlegen (Step 1)**
|
||
- Erstelle die Dateien:
|
||
- schemas/note.schema.json
|
||
- schemas/chunk.schema.json
|
||
- schemas/edge.schema.json
|
||
- schemas/default_edge.schema.json
|
||
- Nutze die in der Playbook‑Datei vorgegebenen Strukturen als Basis.
|
||
- Liefere zusätzlich ein einfaches `Makefile`‑Ziel `schema-validate` (jsonschema via Python), plus `requirements.txt`.
|
||
- Output: komplette Dateien als Downloads + kurze Testanleitung.
|
||
|
||
2) **Qdrant v2‑Collections (Step 2)**
|
||
- Erzeuge die Collections + Payload‑Indizes.
|
||
- Liefere ein kleines Python‑Skript `tools/qdrant_bootstrap_v2.py`, das diese Anlage idempotent durchführt (inkl. Prüf‑Output).
|
||
|
||
3) **Chunker v2 (Step 3)**
|
||
- Implementiere `chunking/block_chunker.py` mit den im Playbook genannten Parametern.
|
||
- Teste gegen 3 Gold‑Notizen (liefere mini Test‑Harness in `tests/gold_notes/…`).
|
||
|
||
Arbeitsweise:
|
||
- Jede Aufgabe einzeln, mit klaren Akzeptanzkriterien (aus Playbook) und Download‑Artefakten.
|
||
- Keine parallelen Großumbauten.
|
||
- Immer deterministische IDs, idempotente Upserts.
|
||
|
||
Dateien, die ich dir anfänglich bereitstelle:
|
||
- **mindnet_v2_implementation_playbook.md** (diese Datei)
|
||
- **import_markdown.py** (aktuelle Version aus dem Projekt)
|
||
- **edges.py** (aktuelle Version aus dem Projekt)
|
||
- **types.yaml** (aktuelle Version)
|
||
|
||
Sage mir jeweils, welche Datei du als Nächstes brauchst. Beginne jetzt mit Aufgabe 1 (Schemata).
|
||
```
|