diff --git a/docs/CHANGELOG_TYPE_REGISTRY.md b/docs/CHANGELOG_TYPE_REGISTRY.md new file mode 100644 index 0000000..8fc095a --- /dev/null +++ b/docs/CHANGELOG_TYPE_REGISTRY.md @@ -0,0 +1,21 @@ +# Changelog — WP-03 Type-Registry (2025-11-08) + +## Added +- `app/core/type_registry.py` — Loader & Helper (cached), robust Fallbacks. +- `config/types.yaml` — Beispiel-Registry (version 1.0). +- `scripts/import_markdown.py` v3.8.0 — Registry-Integration: + - typvalidierung (unbekannt → `concept`, Warnung) + - `chunk_profile` → an `make_chunk_payloads(...)` + - `retriever_weight` → persistiert im Note-Payload + - `edge_defaults["references"]` schaltet Note-Scope-Refs additiv ein +- `app/core/chunk_payload.py` v2.3.0 — optionales `chunk_profile` für + synthetische Overlaps (keine Schemaänderung). +- `app/core/derive_edges.py` v1.5.0 — Type-Registry aktiviert note-scope + References/Backlinks additiv. + +## Changed +- Keine Breaking Changes. Alle CLI-Flags, ENV-Variablen und Collection- + Prefix-Logik bleiben unverändert. + +## Removed +- N/A diff --git a/docs/TYPE_REGISTRY_MANUAL.md b/docs/TYPE_REGISTRY_MANUAL.md new file mode 100644 index 0000000..0bb4640 --- /dev/null +++ b/docs/TYPE_REGISTRY_MANUAL.md @@ -0,0 +1,74 @@ +# Kurzhandbuch — Type-Registry (WP-03) + +## Zweck +Die Type-Registry macht den `type:`-Wert im Frontmatter maschinenlesbar +und steuert: +- Chunk-Profile (indirekt über Overlap bei fensterlosen Chunks), +- typabhängige Default-Kanten (hier: Aktivierung von Note-Scope-References), +- optionale Retriever-Gewichtungen (`retriever_weight`) für WP‑04. + +## Aktivierung +1. Legen Sie `config/types.yaml` an (siehe Beispiel in diesem Paket). +2. Starten Sie Import/Server neu. Die Registry wird beim Prozessstart + geladen und gecached. + +Fehlt die Datei oder ist sie defekt, bleibt das System voll funktionsfähig +(der Typ `concept` wird genutzt; Warnhinweis im Log). + +## Schema (Beispiel) +```yaml +version: 1.0 +types: + concept: + chunk_profile: long + edge_defaults: ["references", "related_to"] + retriever_weight: 1.0 + task: + chunk_profile: short + edge_defaults: ["depends_on", "belongs_to"] + retriever_weight: 0.8 + experience: + chunk_profile: medium + edge_defaults: ["derived_from", "inspired_by"] + retriever_weight: 0.9 + project: + chunk_profile: medium + edge_defaults: ["references", "depends_on"] + retriever_weight: 0.95 +``` + +## Verhalten +- **Chunking**: Die eigentliche Chunk-Länge bleibt weiterhin typabhängig über + `chunk_config.get_sizes(type)` gesteuert. Falls der Chunker keine Fenster + mit Overlap liefert, werden in `chunk_payload` synthetische Fenster erzeugt. + Hier greift das `chunk_profile` mit folgenden Overlap-Empfehlungen: + - short → (20,30), medium → (40,60), long → (60,80). +- **Edges**: Enthält `edge_defaults` den Eintrag `references`, werden Note- + Scope-References/Backlinks additiv aktiviert (kein Abbruch, keine Duplikate). + Weitere Kantenarten bleiben unverändert. +- **Retriever**: `retriever_weight` wird in der Note gespeichert und kann von + WP‑04 im Ranking/Scoring berücksichtigt werden. + +## Tests / Validierung +- Dry-Run: + ```bash + python3 -m scripts.import_markdown --vault ./test_vault + ``` +- Vollimport + Purge: + ```bash + python3 -m scripts.import_markdown --vault ./test_vault --apply --purge-before-upsert --prefix "$COLLECTION_PREFIX" + ``` +- Chunks-Qualität (Window vs Text): + ```bash + python3 tests/check_chunks_window_vs_text.py --prefix "$COLLECTION_PREFIX" + ``` +- Roundtrip: + ```bash + python3 -m scripts.export_markdown --out ./_exportVault --prefix "$COLLECTION_PREFIX" + python3 tests/compare_vaults.py --src ./test_vault --dst ./_exportVault --focus body + ``` + +## Fallbacks & Robustheit +- Registry nicht vorhanden/ungültig → `concept`, Warnung, keine Abbrüche. +- Alle bestehenden ENV/Flags bleiben identisch. +- Keine Änderungen an Punkt-IDs, Feldern oder Vektoren.