# 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.