glpi-neural-brain/ANALYSIS-DASHBOARD.md

BRAIN ANALYSIS CENTER

Das technische Analyse-Dashboard ist bewusst von der animierten Gehirnansicht getrennt.

• Visualisierung: http://localhost:8090/
• Analyse: http://localhost:8090/analysis.html
• Kurzpfad: http://localhost:8090/analysis

In der Gehirnansicht führt der neue Button ANALYSE direkt zum Dashboard.

Zweck

Das Dashboard beantwortet insbesondere:

• Hatte der letzte Lauf ein materiell positives Ergebnis?
• Wurden Nodes, Edges oder Embeddings erzeugt, verändert oder gelöscht?
• Welche konkreten Objekt-IDs waren betroffen?
• Wurde lediglich geprüft und anschließend wegen Qualitätsregeln übersprungen?
• Wie viele semantische Vergleiche, SearXNG-Treffer, Volltextabrufe und akzeptierte Belege gab es?
• Wurde ein Artikel erzeugt oder blieb nur neue Research-Evidence zurück?
• Ist der Graph strukturell gesund und wie hoch ist die Vektorabdeckung?
• Sind Ollama, Autonomous Research, Persistenz und SQLite aktuell arbeitsfähig?

Persistentes Auditprotokoll

Die Historie liegt in BRAIN_DATA_DIR/graph.db. Die Datenbank wird automatisch von Schemaversion 2 auf 3 erweitert. Ein Löschen oder Neuaufbau des Graphen ist nicht erforderlich.

Neue Tabellen:

analysis_events
analysis_points
analysis_changes

analysis_events enthält die ursprünglichen Engine-Aktivitäten mit Query, Meldung, IDs und Metadaten. analysis_points speichert den unmittelbar dazu erfassten Graphstand sowie monotone Änderungszähler. analysis_changes enthält die konkreten betroffenen Nodes, Edges und Vektoren.

Die Historie wird 90 Tage aufbewahrt. Die Aufzeichnung beginnt erst mit dieser Version; frühere Läufe lassen sich nicht rückwirkend rekonstruieren.

Änderungssemantik

Nodes

• created: neue Node-ID wurde aufgenommen.
• updated: vorhandene Node wurde mit geänderten Daten ersetzt.
• deleted: Node ist aus einer verwalteten Quelle verschwunden.

Edges

• created: neue Relation wurde aufgenommen.
• updated: Typ, Status, Confidence, Evidenz oder Metadaten einer vorhandenen Relation wurden geändert.
• deleted: Relation wurde entfernt, etwa weil die Quelle oder ein Endpunkt nicht mehr existiert.

Vektoren

• created: ein Node erhielt erstmals ein Embedding.
• recalculated: ein vorhandenes Embedding wurde ersetzt.
• deleted: ein Vektor wurde invalidiert oder sein Node entfernt.

Eine veränderte semantische Nähe wird sichtbar, wenn eine AI-Edge aktualisiert wird. Reine Kandidatenprüfungen ohne Edge-Übernahme bleiben über die Activity-Metadaten wie semantic_similarity, confidence und candidate_comparisons nachvollziehbar.

Laufbewertung

Das Dashboard fasst zusammengehörige Events zu Läufen zusammen:

• KB-Lernlauf
• AI-THINK-Zyklus
• SearXNG-Recherche
• autonome Rechercheaufgabe
• Wissensabfrage
• Artikelsynthese
• GLPI-Synchronisierung
• Persistenz- und Embedding-Aktionen

Bewertungen:

Bewertung	Bedeutung
positives Ergebnis	mindestens ein Node, eine Edge oder ein Embedding wurde erzeugt
aktualisiert	bestehende Objekte wurden geändert oder Vektoren neu berechnet
Bereinigung	veraltete Objekte wurden entfernt
ohne Übernahme	Prüfung lief, aber Qualitäts-, Relevanz- oder Quellenregeln verhinderten eine Übernahme
ohne Graphänderung	Lauf endete regulär, ohne den Graphzustand zu verändern
fehlgeschlagen	mindestens ein Fehlerereignis gehört zum Lauf

Detailgrenze

Bei sehr großen Erstimporten können zehntausende Nodes und Vektoren in einem einzigen Event entstehen. Deshalb werden pro Event höchstens 2.000 konkrete Detailzeilen persistiert. Die aggregierten Änderungszähler bleiben vollständig und exakt. Das Dashboard weist sichtbar auf gekürzte Detaildaten hin.

Die API liefert standardmäßig die neuesten konkreten Änderungen im gewählten Zeitraum. Dadurch bleibt das Dashboard auch bei großen Wissensbasen bedienbar.

Performance

Die Aufzeichnung selbst ist absichtlich leichtgewichtig:

1. Graphmutationen erhöhen im Speicher konstante Zähler und sammeln begrenzte Detailinformationen.
2. Ein Activity-Event übernimmt den aktuellen Checkpoint in eine asynchrone Queue.
3. Bursts werden bis zu 50 ms beziehungsweise 64 Events gesammelt und gemeinsam in einer SQLite-Transaktion geschrieben.
4. SQLite wird außerhalb des Render- und Engine-Hotpaths beschrieben.
5. Die aufwendige strukturelle Graphanalyse wird erst beim Öffnen des Dashboards berechnet und pro Graphversion gecacht.
6. Die animierte Gehirnansicht lädt die Analysehistorie nicht.

Das Analyse-Dashboard aktualisiert sich über den bestehenden SSE-Stream, aber zusammengefasst und verzögert, damit Event-Bursts nicht für jedes einzelne Ereignis eine neue Vollanalyse auslösen.

HTTP-API

GET /api/analysis/dashboard?hours=24&limit=400
GET /api/analysis/export?hours=24

hours ist auf 1 bis 2.160 Stunden begrenzt. limit steuert die maximale Zahl zurückgegebener Läufe und Events. Der Export liefert dieselbe Struktur als formatiertes JSON und benötigt bei gesetztem BRAIN_API_KEY eine Autorisierung.

Wesentliche Antwortbereiche:

{
  "graph": {
    "summary": {},
    "node_sources": {},
    "edge_types": {},
    "vector_coverage": 0.98,
    "average_ai_confidence": 0.86,
    "average_ai_similarity": 0.91
  },
  "history": {
    "runs": [],
    "events": [],
    "changes": [],
    "totals": {},
    "timeline": [],
    "change_count": 0
  },
  "system": {}
}

Dashboardbereiche

• Ergebnisbewertung des letzten abgeschlossenen Laufs
• aktuelle Graph-, Vektor-, Thinking-, Research-, Ollama- und Persistenzkennzahlen
• Zeitverlauf von Erzeugungen, Aktualisierungen, Löschungen und Events
• filterbares Laufprotokoll mit vollständigen Unterevents
• Source-, Kind-, Origin- und Edge-Verteilungen
• Confidence- und Similarity-Auswertung
• Embedding- und Research-Auswertung
• neueste Nodes und Edges
• exaktes Änderungsjournal
• technischer Roh-Eventstream mit ursprünglichen Metadaten und Graphcheckpoint

Prozess-Lifecycle und Queue-Diagnostik

Research-Unteroperationen werden nicht als eigene Prozesse gezählt. Nur research.started/research.completed beziehungsweise article.research.started/article.research.completed öffnen und schließen einen Research-Lauf. fetch.started, fetch.completed, Ranking-, Material- und Evidence-Events bleiben Unterevents desselben Laufs.

Doppelte Start-Events mit derselben nativen Run-ID erzeugen keinen zweiten aktiven Eintrag. Ältere Relationsrecherchen aus Versionen ohne explizites research.completed werden nach einer Grace-Period anhand eines vorhandenen research.results-Events als Legacy-Abschluss rekonstruiert, statt dauerhaft als läuft angezeigt zu werden.

Die Ollama-Zusammenfassung zeigt neben dem gemeinsamen Active/Waiting-Zähler auch die aktiven/wartenden Operationen für Search, Fetch, Chat und Embedding. Dadurch lässt sich unterscheiden, ob tatsächlich mehrere Arbeiten parallel laufen oder lediglich auf Ollama-/Queue-Kapazität gewartet wird.