138 lines
7.8 KiB
Markdown
138 lines
7.8 KiB
Markdown
# Neural Knowledge Brain
|
||
|
||
Eigenständiger Go-Dienst für deine beiden GLPI-Projekte. Er liest die produktive Wissensbasis und Agent-Audits **read-only**, erzeugt einen dynamischen Wissensgraphen und rendert dessen Aktivität als fullscreen „Gehirn“. Neue KI-Synthesen werden ausschließlich als **AI-THINK** in das vorhandene Knowledgebase-Staging geschrieben.
|
||
|
||
## Was bereits implementiert ist
|
||
|
||
- Fullscreen Canvas-Rendering in Gehirnform, ohne Frontend-Framework oder externe CDN-Abhängigkeit.
|
||
- Echtzeitaktivierung über Server-Sent Events: Nodes glühen, Edges leuchten, Partikel laufen entlang verwendeter Verbindungen.
|
||
- Direkter Ingest der vorhandenen Knowledge-JSONs einschließlich Kategorien, Keywords, Quellen und Staging-Status.
|
||
- Read-only Tailing von `runs.jsonl` des Agents; neue Agent-Läufe erscheinen als Hirnaktivität.
|
||
- Optionale, nicht blockierende Telemetrie-Patches für Agent- und Knowledgebase-Suchanfragen.
|
||
- Embeddings über Ollama `embeddinggemma`; lokaler Feature-Hash-Fallback, falls Ollama gerade nicht erreichbar ist.
|
||
- Suchanfragen über Agent, Knowledgebase oder API: Retrieval, aktivierte Nodes/Edges und strukturierte Verarbeitung durch `qwen3:8b`. Die Webansicht bleibt bewusst eine reine Visualisierung ohne Eingabefeld.
|
||
- Sequenzielle, automatische Verknüpfungsanalyse. Es wird immer nur ein Kandidatenpaar gleichzeitig geprüft.
|
||
- KI-Edges mit Herkunft, Confidence, Erklärung und Evidenz. Abgelehnte Paare werden intern markiert, damit sie nicht endlos erneut geprüft werden.
|
||
- Optional kontrollierte Recherche über eine eigene SearXNG-Instanz.
|
||
- Automatische AI-THINK-Beiträge im bestehenden Staging-JSON-Format, stets mit `auto_reply: false`.
|
||
|
||
|
||
## Automatische Visualzustände
|
||
|
||
Die Fullscreen-Ansicht wechselt selbstständig zwischen drei Darstellungsstufen:
|
||
|
||
- **LIVING:** ruhige Eigenaktivität mit langsamer Atmung semantischer Cortex-Areale, vereinzelten internen Impulsen und sanfter Kamerabewegung. Diese Mikroaktivität wird nicht als wichtiges Feed-Ereignis protokolliert.
|
||
- **ACTIVATION:** Agent-Suchen, Knowledgebase-Suchen und Graph-Updates fokussieren automatisch den betroffenen Wissensbereich. Aktive Regionen dehnen sich leicht aus; relevante Edges transportieren Partikel.
|
||
- **AI-THINK / RESEARCH:** Beziehungsanalyse und Recherche erhalten einen stärkeren visuellen Modus mit fokussierter Kamera, konzentrischen Wellen, Synapsen-Bursts und statusabhängigen Farben.
|
||
|
||
Die Themenstruktur wird nicht nur aus dem ersten Kategorie-Feld abgeleitet. Kategorien bilden feste Anker; Konzepte, Quellen und externe Recherche-Nodes übernehmen über gewichtete Nachbarschafts-Propagation das stärkste verbundene Themengebiet. Verwandte Bereiche ziehen sich an, nicht verwandte Bereiche stoßen sich ab. Die zwölf stärksten Cortex-Areale erhalten bewusst deutlich getrennte Farben.
|
||
|
||
Der Aktivitätsfeed zeigt nur relevante Ereignisse und ergänzt – sofern vorhanden – Cortex-Bereich, Trefferzahl, verwendete Quellen, Laufzeit, semantische Nähe, Relationstyp, Konfidenz, Recherchequellen, Ticket-ID und Staging-Pfad.
|
||
|
||
## Schutz der Basisprojekte
|
||
|
||
Das Brain bekommt nur:
|
||
|
||
- `knowledge/` **read-only**
|
||
- `data/runs.jsonl` **read-only**
|
||
- `staging/` **read-write**
|
||
|
||
Der Agent erhält weiterhin keinen Zugriff auf das Staging. Im integrierten Compose-Stack erhält auch `kb-search` nur ein leeres, flüchtiges Staging; ausschließlich der Prüf-Editor und das Brain sehen die echten Entwürfe. Die bestehende Knowledgebase nimmt AI-THINK erst nach deiner Freigabe in den produktiven Bestand. Damit kann das Brain die Entwürfe bereits darstellen und beim Denken berücksichtigen, während Agent und produktive Suche sie noch nicht sehen.
|
||
|
||
## Schnellstart nativ
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# Pfade in .env anpassen
|
||
ollama pull qwen3:8b
|
||
ollama pull embeddinggemma
|
||
set -a; . ./.env; set +a
|
||
go run ./cmd/brain
|
||
```
|
||
|
||
Windows PowerShell:
|
||
|
||
```powershell
|
||
Copy-Item .env.example .env
|
||
# Variablen aus .env setzen oder direkt in der Sitzung definieren
|
||
go run ./cmd/brain
|
||
```
|
||
|
||
Oberfläche: `http://localhost:8090`
|
||
|
||
Ohne Ollama startet die Visualisierung trotzdem. Retrieval verwendet dann einen deterministischen lokalen Fallback; Qwen-Synthesen und belastbare AI-Inferenz benötigen Ollama.
|
||
|
||
## Docker
|
||
|
||
Passe in `docker-compose.yml` die drei Host-Pfade an und starte:
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
Auf Linux ist `host.docker.internal` über `extra_hosts` eingebunden. Alternativ kann das Brain in dasselbe Docker-Netz wie Ollama aufgenommen und `OLLAMA_URL=http://ollama:11434` gesetzt werden.
|
||
|
||
## Ablauf einer sichtbaren Anfrage
|
||
|
||
1. Die Anfrage erzeugt eine Wahrnehmungswelle.
|
||
2. EmbeddingGemma bewertet passende Knowledge- und AI-THINK-Nodes.
|
||
3. Treffer leuchten nacheinander auf.
|
||
4. Vorhandene Verbindungen werden durchlaufen und mit Partikeln dargestellt.
|
||
5. Qwen3:8b erhält ausschließlich den ausgewählten Kontext.
|
||
6. Die final verwendeten Nodes und Edges pulsieren bei der Antwortsynthese.
|
||
|
||
## Automatische Anreicherung
|
||
|
||
Der Enrichment-Loop arbeitet bewusst seriell:
|
||
|
||
1. ähnlichstes noch ungeprüftes Wissenspaar auswählen;
|
||
2. Qwen-Beziehungsanalyse mit festem JSON-Schema;
|
||
3. Edge als `staging` oder intern als `rejected` speichern;
|
||
4. bei Unklarheit optional SearXNG-Recherche durchführen;
|
||
5. externe Quellen als eigene Nodes mit Evidence-Edges anlegen;
|
||
6. AI-THINK-JSON atomar in `BRAIN_STAGING_DIRS` schreiben;
|
||
7. beim nächsten Scan den neuen Beitrag als sichtbaren und durchsuchbaren Staging-Node aufnehmen.
|
||
|
||
Ein erzeugter Entwurf enthält zusätzlich ein `ai_think`-Objekt mit Quell-Nodes, Relation, Confidence, Forschungsstatus und Evidenz. Die vorhandene Editor-Raw-JSON-Ansicht kann diese Daten bereits anzeigen.
|
||
|
||
## Minimale optionale Integrationen
|
||
|
||
Die Patches unter `integrations/` senden echte Suchanfragen und Treffer an `POST /api/events`:
|
||
|
||
```bash
|
||
# im jeweiligen Projekt-Root
|
||
git apply /pfad/glpi-neural-brain/integrations/agent/glpi-ai-agent-neural-brain.patch
|
||
git apply /pfad/glpi-neural-brain/integrations/knowledgebase/glpi-ai-knowledgebase-neural-brain.patch
|
||
```
|
||
|
||
Danach optional setzen:
|
||
|
||
```env
|
||
BRAIN_ACTIVITY_URL=http://brain:8090/api/events
|
||
BRAIN_ACTIVITY_API_KEY=
|
||
```
|
||
|
||
Ist `BRAIN_ACTIVITY_URL` leer, ist die Integration vollständig deaktiviert. Das Senden ist asynchron, fail-open, auf drei Sekunden begrenzt und kann weder Ticketverarbeitung noch KB-Suche blockieren. Der Agent funktioniert zusätzlich auch ohne Patch: Das Brain beobachtet weiterhin sein `runs.jsonl`.
|
||
|
||
## HTTP-Endpunkte
|
||
|
||
| Methode | Pfad | Zweck |
|
||
|---|---|---|
|
||
| `GET` | `/api/status` | Zustand, Modelle und Zähler |
|
||
| `GET` | `/api/graph` | kompletter aktueller Graph |
|
||
| `GET` | `/api/analysis` | Komponenten, Hubs, AI-Edges, Widersprüche und unverknüpftes Wissen |
|
||
| `GET` | `/api/stream` | SSE-Aktivitätsstrom |
|
||
| `POST` | `/api/query` | sichtbare Wissensanfrage |
|
||
| `POST` | `/api/events` | optionale Agent-/KB-Telemetrie |
|
||
| `POST` | `/api/reindex` | Scan und Embedding-Abgleich |
|
||
| `POST` | `/api/enrich` | genau einen AI-THINK-Schritt ausführen |
|
||
|
||
Mit `BRAIN_API_KEY` werden alle POST-Endpunkte über `Authorization: Bearer …` oder `X-Brain-Key` geschützt. Die Webansicht ruft keine Query-POSTs mehr auf. Der API-Key schützt weiterhin Integrationen, Reindex, Enrichment und externe Query-Aufrufe; produktiv sollte der Dienst lokal oder hinter einem authentifizierenden Reverse Proxy betrieben werden.
|
||
|
||
## Grenzen des Prototyps
|
||
|
||
- Der Graphspeicher ist eine atomar geschriebene JSON-Datei und für einen einzelnen Brain-Prozess ausgelegt. Für sehr große Bestände wäre eine spätere Migration auf einen spezialisierten Graph-/Vektorspeicher sinnvoll.
|
||
- Webrecherche ist absichtlich nur über eine explizit konfigurierte SearXNG-Instanz aktiv.
|
||
- KI-Edges bleiben Hypothesen. Erst eine Freigabe des AI-THINK-Beitrags macht daraus produktives Knowledge; die Edge selbst trägt weiterhin ihre KI-Herkunft.
|
||
- Das System löst Widersprüche nicht stillschweigend auf. `contradicts` ist ein eigener Edge-Typ und bleibt sichtbar.
|