mindnet_obsidian/docs/06_Konfigurationsdateien_Referenz.md

Mindnet Causal Assistant - Konfigurationsdateien Referenz

Version: 1.0.0
Stand: 2025-01-XX
Zielgruppe: Administratoren, Config-Manager

---

Inhaltsverzeichnis

1. Überblick
2. Edge Vocabulary (edge_vocabulary.md)
3. Graph Schema (graph_schema.md)
4. Interview Config (interview_config.yaml)
5. Chain Roles (chain_roles.yaml)
6. Chain Templates (chain_templates.yaml)
7. Analysis Policies (analysis_policies.yaml)

---

Überblick

Das Mindnet Causal Assistant Plugin verwendet mehrere Konfigurationsdateien, die im Vault gespeichert werden. Diese Dateien definieren:

• Edge Vocabulary: Kanonische Edge-Typen und Aliases
• Graph Schema: Empfehlungen für Edge-Typen basierend auf Note-Typen
• Interview Config: Profile, Steps, Loops für Note-Erstellung
• Chain Roles: Mapping von Edge-Typen zu kausalen Rollen
• Chain Templates: Vordefinierte Kettenmuster für Template Matching
• Analysis Policies: Policies für Findings (Severity, Unterdrückung)

---

Edge Vocabulary (edge_vocabulary.md)

Zweck

Definiert kanonische Edge-Typen und ihre Aliases für Normalisierung und Lookup.

Format

Markdown-Datei mit Tabellen-Struktur.

Struktur

# Edge Vocabulary

### Kategorie 1

| System-Typ (Canonical) | Inverser Typ | Erlaubte Aliasse (User) | Beschreibung | Kategorie |
| :--- | :--- | :--- | :--- | :--- |
| **`causes`** | `caused_by` | `verursacht`, `führt_zu` | Direkte Kausalität | Kausal |
| **`caused_by`** | `causes` | `ausgelöst_durch`, `wegen` | Umgekehrte Kausalität | Kausal |

### Kategorie 2

| System-Typ (Canonical) | Inverser Typ | Erlaubte Aliasse (User) | Beschreibung | Kategorie |
| :--- | :--- | :--- | :--- | :--- |
| **`influences`** | `influenced_by` | `beeinflusst`, `wirkt_auf` | Einfluss-Beziehung | Einfluss |

Parsing-Regeln

1. H3-Überschriften (###) werden als Kategorien erkannt
2. Tabellen werden geparst:
   • Erste Spalte: Canonical Type (kann mit ** fett formatiert sein)
   • Zweite Spalte: Inverse Type (optional)
   • Dritte Spalte: Aliases (komma-separiert, optional)
   • Weitere Spalten: Beschreibung, Kategorie (optional)
3. Backticked Tokens (\type``) werden extrahiert
4. Header-Zeilen werden übersprungen (enthält "Canonical", "System-Typ", etc.)
5. Leere Zeilen oder Zeilen ohne Tokens werden übersprungen

Beispiel

# Edge Vocabulary

### Kausale Beziehungen

| System-Typ (Canonical) | Inverser Typ | Erlaubte Aliasse (User) | Beschreibung |
| :--- | :--- | :--- | :--- |
| **`causes`** | `caused_by` | `verursacht`, `führt_zu` | Direkte Kausalität |
| **`caused_by`** | `causes` | `ausgelöst_durch`, `wegen` | Umgekehrte Kausalität |

### Einfluss-Beziehungen

| System-Typ (Canonical) | Inverser Typ | Erlaubte Aliasse (User) | Beschreibung |
| :--- | :--- | :--- | :--- |
| **`influences`** | `influenced_by` | `beeinflusst`, `wirkt_auf` | Einfluss-Beziehung |

Verwendung

• Normalisierung: vocabulary.normalize("ausgelöst_durch") → { canonical: "caused_by", inverse: "causes" }
• Lookup: vocabulary.getCanonical("verursacht") → "causes"
• Inverse: vocabulary.getInverse("causes") → "caused_by"

---

Graph Schema (graph_schema.md)

Zweck

Definiert Empfehlungen für Edge-Typen basierend auf Source- und Target-Note-Typen.

Format

Markdown-Datei mit Sections und Tabellen.

Struktur

# Graph Schema

## Source: `experience`

| Target Type | Typical | Prohibited |
| :--- | :--- | :--- |
| `insight` | `causes`, `influences` | `part_of`, `instance_of` |
| `decision` | `influences` | `causes` |

## Source: `insight`

| Target Type | Typical | Prohibited |
| :--- | :--- | :--- |
| `decision` | `causes`, `enables` | `influences` |

Parsing-Regeln

1. H2-Überschriften mit Pattern ## Source: \type`` werden als Source-Typ erkannt
2. Tabellen werden geparst:
   • Erste Spalte: Target Type (in Backticks)
   • Zweite Spalte: Typical Edge Types (komma-separiert)
   • Dritte Spalte: Prohibited Edge Types (komma-separiert)
3. Header-Zeilen werden übersprungen
4. Leere Zeilen werden übersprungen

Beispiel

# Graph Schema

## Source: `experience`

| Target Type | Typical | Prohibited |
| :--- | :--- | :--- |
| `insight` | `causes`, `influences` | `part_of` |
| `decision` | `influences` | `causes` |

## Source: `insight`

| Target Type | Typical | Prohibited |
| :--- | :--- | :--- |
| `decision` | `causes`, `enables` | `influences` |

Verwendung

• Edge-Type-Selector: Zeigt Empfehlungen basierend auf Source-Note-Type
• Warnungen: Zeigt Warnungen bei prohibited Types
• Lookup: schema.getTypicalEdgeTypes("experience", "insight") → ["causes", "influences"]

---

Interview Config (interview_config.yaml)

Zweck

Definiert Profile, Steps, Loops für Note-Erstellung und Interviews.

Format

YAML-Datei mit strukturierter Hierarchie.

Struktur

version: "2.0"
frontmatter_whitelist:
  - tags
  - status

profiles:
  - key: experience_basic
    label: "Erfahrung (Basis)"
    note_type: experience
    description: "Basic experience profile"
    defaults:
      folder: "experiences"
      tags: ["experience"]
    steps:
      - id: context
        prompt: "Beschreibe den Kontext"
        input_type: textarea
        required: true
      - id: details
        prompt: "Weitere Details"
        input_type: textarea
        required: false
    post_run:
      edger: true

Felder

Root-Level

• version (string, optional): Config-Version (Standard: "2.0")
• frontmatter_whitelist (array of strings, optional): Erlaubte Frontmatter-Keys (zusätzlich zu Standard)
• profiles (array, required): Liste von Profilen

Profile

• key (string, required): Eindeutiger Profil-Schlüssel
• label (string, required): Anzeige-Name
• note_type (string, required): Note-Type (z.B. experience, insight, decision)
• description (string, optional): Beschreibung
• defaults (object, optional): Standardwerte
  • folder (string, optional): Standard-Ordner
  • tags (array of strings, optional): Standard-Tags
  • Weitere Felder möglich
• steps (array, optional): Interview-Steps
• post_run (object, optional): Post-Run-Actions
  • edger (boolean, optional): Semantic Mapping Builder ausführen

Step

• id (string, required): Eindeutige Step-ID
• prompt (string, required): Prompt-Text
• input_type (string, required): Input-Typ (text, textarea, select, etc.)
• required (boolean, optional): Ob Step erforderlich ist
• default (string, optional): Standardwert
• options (array, optional): Optionen für select Input-Type
• loop (object, optional): Loop-Konfiguration
  • key (string, required): Loop-Key
  • prompt (string, required): Loop-Prompt
  • min_items (number, optional): Minimale Anzahl Items
  • max_items (number, optional): Maximale Anzahl Items
  • nested_loops (array, optional): Verschachtelte Loops

Beispiel

version: "2.0"
frontmatter_whitelist:
  - tags
  - status

profiles:
  - key: experience_basic
    label: "Erfahrung (Basis)"
    note_type: experience
    description: "Basic experience profile"
    defaults:
      folder: "experiences"
      tags: ["experience"]
    steps:
      - id: context
        prompt: "Beschreibe den Kontext"
        input_type: textarea
        required: true
      - id: events
        prompt: "Wichtige Ereignisse"
        input_type: textarea
        loop:
          key: events
          prompt: "Ereignis"
          min_items: 1
          max_items: 10
    post_run:
      edger: true

  - key: insight_basic
    label: "Einsicht (Basis)"
    note_type: insight
    defaults:
      folder: "insights"
    steps:
      - id: insight
        prompt: "Beschreibe die Einsicht"
        input_type: textarea
        required: true

Verwendung

• Profil-Auswahl: Profile werden in ProfileSelectionModal angezeigt
• Wizard: Steps werden als Wizard-Steps angezeigt
• Frontmatter: Frontmatter wird mit Whitelist generiert
• Post-Run: Actions werden nach Wizard ausgeführt

---

Chain Roles (chain_roles.yaml)

Zweck

Mappt Edge-Typen zu kausalen Rollen für Template Matching.

Format

YAML-Datei mit strukturierter Hierarchie.

Struktur

version: "1.0"

roles:
  causal:
    description: "Direkte kausale Beziehungen"
    edge_types:
      - causes
      - caused_by
      - resulted_in
  influences:
    description: "Einfluss-Beziehungen"
    edge_types:
      - influences
      - affects
  enables_constraints:
    description: "Ermöglicht/Beschränkt-Beziehungen"
    edge_types:
      - enables
      - constrains
  provenance:
    description: "Herkunfts-Beziehungen"
    edge_types:
      - derived_from
      - based_on

Felder

Root-Level

• version (string, optional): Config-Version
• roles (object, required): Mapping von Rollen-Namen zu Rollen-Definitionen

Role

• description (string, optional): Beschreibung der Rolle
• edge_types (array of strings, required): Liste von Edge-Typen, die zu dieser Rolle gehören

Standard-Rollen

• causal: Direkte kausale Beziehungen
• influences: Einfluss-Beziehungen
• enables_constraints: Ermöglicht/Beschränkt-Beziehungen
• provenance: Herkunfts-Beziehungen

Beispiel

version: "1.0"

roles:
  causal:
    description: "Direkte kausale Beziehungen"
    edge_types:
      - causes
      - caused_by
      - resulted_in
      - resulted_from
  influences:
    description: "Einfluss-Beziehungen"
    edge_types:
      - influences
      - affects
      - impacts
  enables_constraints:
    description: "Ermöglicht/Beschränkt-Beziehungen"
    edge_types:
      - enables
      - constrains
      - limits
  provenance:
    description: "Herkunfts-Beziehungen"
    edge_types:
      - derived_from
      - based_on
      - originates_from

Verwendung

• Template Matching: Edge-Typen werden zu Rollen gemappt für Link-Constraints
• Findings: no_causal_roles Finding wird generiert, wenn keine causal Rollen gefunden werden
• Lookup: chainRoles.getRoleForEdgeType("causes") → "causal"

---

Chain Templates (chain_templates.yaml)

Zweck

Definiert vordefinierte Kettenmuster für Template Matching.

Format

YAML-Datei mit strukturierter Hierarchie.

Struktur

version: "1.0"

defaults:
  matching:
    required_links: false

templates:
  - name: trigger_transformation_outcome
    description: "Causal chain template"
    slots:
      - id: trigger
        allowed_node_types: ["experience"]
      - id: transformation
        allowed_node_types: ["insight"]
      - id: outcome
        allowed_node_types: ["decision"]
    links:
      - from: trigger
        to: transformation
        allowed_edge_roles: ["causal"]
      - from: transformation
        to: outcome
        allowed_edge_roles: ["causal"]
    matching:
      required_links: true

Felder

Root-Level

• version (string, optional): Config-Version
• defaults (object, optional): Standardwerte
  • matching (object, optional): Standard-Matching-Parameter
    • required_links (boolean, optional): Ob Links erforderlich sind (Standard: false)
  • profiles (object, optional): Profil-spezifische Defaults
    • discovery (object, optional): Discovery-Profil-Parameter
    • decisioning (object, optional): Decisioning-Profil-Parameter
• templates (array, required): Liste von Templates

Template

• name (string, required): Template-Name
• description (string, optional): Beschreibung
• slots (array, required): Slot-Definitionen
• links (array, optional): Link-Constraints
• matching (object, optional): Matching-Parameter (überschreibt Defaults)
  • required_links (boolean, optional): Ob Links erforderlich sind

Slot

• id (string, required): Slot-ID
• allowed_node_types (array of strings, required): Erlaubte Note-Types für diesen Slot

Link

• from (string, required): Source-Slot-ID
• to (string, required): Target-Slot-ID
• allowed_edge_roles (array of strings, required): Erlaubte Edge-Rollen

Beispiel

version: "1.0"

defaults:
  matching:
    required_links: false
  profiles:
    discovery:
      required_links: false
      min_slots_filled_for_gap_findings: 1
      min_score_for_gap_findings: 0
    decisioning:
      required_links: true
      min_slots_filled_for_gap_findings: 2
      min_score_for_gap_findings: 10

templates:
  - name: trigger_transformation_outcome
    description: "Causal chain: trigger → transformation → outcome"
    slots:
      - id: trigger
        allowed_node_types: ["experience", "event"]
      - id: transformation
        allowed_node_types: ["insight"]
      - id: outcome
        allowed_node_types: ["decision", "action"]
    links:
      - from: trigger
        to: transformation
        allowed_edge_roles: ["causal"]
      - from: transformation
        to: outcome
        allowed_edge_roles: ["causal"]
    matching:
      required_links: true

  - name: loop_learning
    description: "Learning loop: experience → learning → behavior → feedback"
    slots:
      - id: experience
        allowed_node_types: ["experience"]
      - id: learning
        allowed_node_types: ["insight", "learning"]
      - id: behavior
        allowed_node_types: ["decision", "action"]
      - id: feedback
        allowed_node_types: ["experience", "event"]
    links:
      - from: experience
        to: learning
        allowed_edge_roles: ["causal", "influences"]
      - from: learning
        to: behavior
        allowed_edge_roles: ["causal"]
      - from: behavior
        to: feedback
        allowed_edge_roles: ["causal", "influences"]
      - from: feedback
        to: experience
        allowed_edge_roles: ["causal", "influences"]

Verwendung

• Template Matching: Templates werden gegen lokalen Subgraph gematcht
• Findings: missing_slot_* Findings werden generiert, wenn Slots fehlen
• Link Constraints: missing_link_constraints Finding wird generiert, wenn Links fehlen (wenn required_links=true)

---

Analysis Policies (analysis_policies.yaml)

Zweck

Definiert Policies für Findings (Severity, Unterdrückung, etc.).

Format

YAML-Datei (geplant, noch nicht vollständig implementiert).

Geplante Struktur

version: "1.0"

findings:
  missing_slot_*:
    default_severity: warn
    profiles:
      discovery:
        severity: info
        suppress_if:
          - slots_filled < 2
      decisioning:
        severity: warn
        suppress_if: []
  dangling_target:
    default_severity: error
    suppress_if: []
  missing_link_constraints:
    default_severity: warn
    suppress_if:
      - required_links == false
  no_causal_roles:
    default_severity: info
    suppress_if: []

Felder (geplant)

Root-Level

• version (string, optional): Config-Version
• findings (object, required): Mapping von Finding-Codes zu Policies

Finding Policy

• default_severity (string, required): Standard-Severity (error, warn, info)
• profiles (object, optional): Profil-spezifische Overrides
  • discovery (object, optional): Discovery-Profil-Parameter
  • decisioning (object, optional): Decisioning-Profil-Parameter
• suppress_if (array, optional): Bedingungen für Unterdrückung

Status

Noch nicht vollständig implementiert. Aktuell wird Severity-Policy teilweise in severityPolicy.ts gehandhabt.

---

Validierung & Fehlerbehandlung

YAML-Dateien

• Syntax-Fehler: Werden beim Laden erkannt und geloggt
• Last-Known-Good: Letzte gültige Config wird bei Fehlern verwendet
• Warnings: Ungültige Felder werden als Warnings geloggt, nicht als Fehler

Markdown-Dateien

• Parsing-Fehler: Werden beim Laden erkannt und geloggt
• Fehlende Felder: Werden ignoriert oder mit Defaults gefüllt
• Warnings: Ungültige Zeilen werden übersprungen

Live-Reload

• Debounced: 200ms Delay für Performance
• Automatisch: Bei Dateiänderungen
• Manuell: Über Commands möglich

---

Best Practices

Versionierung

• Verwenden Sie Versionsnummern in Config-Dateien
• Dokumentieren Sie Änderungen
• Testen Sie Änderungen in Test-Vault

Struktur

• Verwenden Sie klare, konsistente Namen
• Kommentieren Sie komplexe Konfigurationen
• Gruppieren Sie verwandte Einträge

Wartung

• Regelmäßige Backups
• Git-Versionierung empfohlen
• Dokumentation von Custom-Konfigurationen

---

Ende der Konfigurationsdateien Referenz