# 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 mit sichtbarem Worker-Status. Pro Zyklus werden standardmäßig bis zu drei Kandidaten nacheinander geprüft; niemals parallel.
- 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. Der Statusblock zeigt außerdem, ob der autonome Worker läuft, wartet, keine Kandidaten findet oder Ollama nicht erreicht. Über den wieder eingeblendeten **AI-THINK**-Button kann jederzeit ein manueller Zyklus angestoßen werden.

## 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. Die Kandidatensuche verwendet einen rotierenden, begrenzten Anchor-Satz statt eines vollständigen O(n²)-Vergleichs über den gesamten Graphen. Dadurch bleibt sie auch bei zehntausenden Nodes reaktionsfähig und besucht langfristig trotzdem den gesamten Wissensbestand.

1. einen rotierenden Bereich des Graphen nach dem stärksten noch ungeprüften Wissenspaar durchsuchen;
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.


### AI-THINK-Taktung

```env
BRAIN_AUTO_ENRICH=true
BRAIN_ENRICH_INTERVAL=90s
BRAIN_ENRICH_BATCH_SIZE=3
BRAIN_ENRICH_STEP_DELAY=3s
BRAIN_ENRICH_ANCHORS=48
```

`BRAIN_ENRICH_BATCH_SIZE` bestimmt, wie viele Beziehungen pro autonomem Zyklus nacheinander geprüft werden. `BRAIN_ENRICH_ANCHORS` begrenzt die CPU-seitige Kandidatensuche je Schritt. Die GPU wird nur während echter Qwen- oder Embedding-Aufrufe belastet; zwischen den Zyklen ist eine geringe oder null GPU-Auslastung normal.

## 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` | einen AI-THINK-Schritt synchron ausführen |
| `POST` | `/api/enrich?async=1` | einen vollständigen sequenziellen AI-THINK-Zyklus einplanen |

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.