# Neural Knowledge Brain

Eigenständiger Go-Dienst für Agent, lokale Knowledgebase, GLPI-Knowledgebase und autonome AI-THINK-Anreicherung. Der Dienst hält einen vollständigen Wissensgraphen im Arbeitsspeicher und rendert eine hierarchisch verdichtete Fullscreen-Ansicht als lebende Hirnaktivität.

## Kernfunktionen

- Fullscreen-Canvas mit 3D-Hirnform, semantischen Cortex-Regionen und hierarchischem Level-of-Detail.
- Umschaltbare Honeycomb-Ansicht: gleichmäßig verteilte Notes in einer automatisch skalierten 3D-Gehirnwabe, ohne Edge-Rendering.
- Laufzeitsteuerung für Learning und Thinking sowie getrennte Kategorie-Filter für Lernen, Anzeige und AI-THINK.
- Echtzeitaktivierung über Server-Sent Events: Nodes glühen, aggregierte Edges leuchten und Partikel folgen tatsächlichen Wissenspfaden.
- Ingest lokaler produktiver Knowledge-JSONs sowie separater AI-THINK-Staging-Dateien.
- Optionaler read-only Ingest sichtbarer Beiträge aus der GLPI-Knowledgebase.
- Read-only Tailing der Agent-`runs.jsonl` und optionale Suchtelemetrie aus Agent und KB.
- Ollama-Pool mit mehreren unabhängigen Instanzen, Routing, Healthchecks, Cooldown und Failover.
- Embeddings über `embeddinggemma`, Beziehungsanalyse über `qwen3:8b`.
- Sequenzieller autonomer AI-THINK-Worker mit optionaler SearXNG-Recherche.
- Gebündelte Festplattenpersistenz: Graph, GLPI-KB-Cache und AI-THINK-Dateien werden standardmäßig nur alle fünf Minuten sequenziell geschrieben.

## Vertrauens- und Schreibgrenzen

Das Brain liest produktive Quellen und GLPI-KB ausschließlich. Es schreibt niemals in produktive Knowledge-Dateien oder nach GLPI zurück.

Schreibbar sind nur:

- das eigene `BRAIN_DATA_DIR` für Graphzustand und GLPI-KB-Cache;
- der erste Pfad aus `BRAIN_STAGING_DIRS` für AI-THINK-Entwürfe.

AI-THINK bleibt `auto_reply: false`, trägt die Kategorien `AI-THINK` und `AI-Staging` und wird erst nach einer expliziten Freigabe im bestehenden Editor produktiv.

## Schnellstart

```bash
cp .env.example .env
# Pfade, Ollama-Pool und optional GLPI-Zugangsdaten anpassen.
set -a; . ./.env; set +a
go run ./cmd/brain
```

Oberfläche: `http://localhost:8090`

Docker:

```bash
docker compose up -d --build
```

## Mehrere Ollama-Instanzen

`OLLAMA_URLS` hat Vorrang vor dem weiterhin unterstützten `OLLAMA_URL`.

```env
OLLAMA_URLS=http://10.20.30.21:11434,http://10.20.30.22:11434,http://10.20.30.23:11434
OLLAMA_NODE_NAMES=gpu-01,gpu-02,gpu-03
OLLAMA_NODE_WEIGHTS=1,1,4
OLLAMA_ROUTING_MODE=least_inflight
OLLAMA_NODE_MAX_INFLIGHT=1
OLLAMA_FAILOVER_ENABLED=true
OLLAMA_FAILOVER_ATTEMPTS=0
OLLAMA_REQUIRE_SAME_MODEL_DIGEST=true
OLLAMA_REQUIRE_EMBEDDING_MODEL=true
```

Unterstützte Routing-Modi:

- `least_inflight` – bevorzugt den aktuell am wenigsten belasteten Node;
- `round_robin` – zyklische Verteilung;
- `weighted` – Verteilung entsprechend `OLLAMA_NODE_WEIGHTS`;
- `fastest_recent` – bevorzugt die zuletzt schnellsten Nodes.

Jeder Node muss das Chatmodell besitzen. Mit `OLLAMA_REQUIRE_EMBEDDING_MODEL=true` muss außerdem jeder Node das Embeddingmodell besitzen. Bei aktivierter Digest-Prüfung wird ein Pool mit unterschiedlichen Modellständen fail-closed behandelt.

Mehr Details: [`OLLAMA-POOL.md`](OLLAMA-POOL.md).

## GLPI-Knowledgebase einbeziehen

Die Integration verwendet denselben read-only OAuth-/OpenAPI-Ansatz wie der Agent. GLPI entscheidet anhand des Service-Accounts, welche Beiträge sichtbar sind.

```env
GLPI_KB_ENABLED=true
GLPI_URL=https://glpi.example.org
GLPI_API_VERSION=v2.3
GLPI_CLIENT_ID=...
GLPI_CLIENT_SECRET=...
GLPI_USERNAME=...
GLPI_PASSWORD=...
GLPI_KB_PATH=auto
GLPI_KB_LIMIT=500
GLPI_KB_SYNC_INTERVAL=10m
GLPI_KB_SOURCE=GLPI Knowledge Base
```

Bei `GLPI_KB_PATH=auto` sucht das Brain im GLPI-OpenAPI-Dokument die lesbare `KnowbaseItem`-Collection. Die Beiträge werden als produktive Wissens-Nodes mit `glpi://KnowbaseItem/<id>`-URI aufgenommen. Kategorien und Quelle erzeugen verifizierte Edges. Es gibt keine GLPI-Schreiboperation.

Manueller Sync:

```bash
curl -X POST http://localhost:8090/api/glpi-kb/sync
```

Mehr Details: [`GLPI-KB.md`](GLPI-KB.md).

## Gebündelte Persistenz

```env
BRAIN_PERSIST_INTERVAL=5m
```

Im Arbeitsspeicher sind neue Nodes, Edges und AI-THINK-Ergebnisse sofort verfügbar. Auf die Festplatte wird jedoch sequenziell geschrieben:

1. ausstehende AI-THINK- und Cache-Dateien atomar, Pfad für Pfad;
2. anschließend genau ein Graph-Snapshot;
3. zusätzlich ein finaler Flush beim geregelten Shutdown.

Das reduziert Schreibzugriffe deutlich. Der Preis ist ein konfigurierbares Durability-Fenster: Bei einem harten Stromausfall können die seit dem letzten Flush entstandenen Änderungen fehlen.

Manueller Flush:

```bash
curl -X POST http://localhost:8090/api/flush
```

Mehr Details: [`PERSISTENCE.md`](PERSISTENCE.md).

## Laufzeitsteuerung und Honeycomb

Die untere Steuerleiste enthält direkte Schalter für **LEARNING**, **THINKING**, **NEURAL** und **HONEYCOMB**. Sind Learning und Thinking deaktiviert, bleibt das System im Living-Modus; eingehende Agent- oder KB-Anfragen können weiterhin die tatsächlich verwendeten Notes aktivieren.

Über **FILTER** lassen sich drei unabhängige Kategorienlisten pflegen:

- **Lernen**: neue Embeddings nur für passende Kategorien;
- **Anzeige**: Browser-Rendering nur für passende Notes;
- **Thinking**: neue AI-THINK-Kandidaten nur innerhalb der gewählten Kategorien.

Leere Listen bedeuten „alle Kategorien“. Die Werte werden über die vorhandene Persistenzqueue in `runtime-settings.json` geschrieben.

```env
BRAIN_LEARNING_ENABLED=true
BRAIN_THINKING_ENABLED=true
BRAIN_LEARNING_CATEGORIES=
BRAIN_DISPLAY_CATEGORIES=
BRAIN_THINKING_CATEGORIES=
BRAIN_DEFAULT_VIEW=neural
```

Honeycomb rendert nur `knowledge`, `ai-think` und `external`. Ein 3D-Gitter mit einheitlichem Punktabstand wird auf die Gehirngeometrie beschnitten und automatisch an die sichtbare Anzahl von Notes angepasst. Edges, LOD-Gruppen und Cortex-Flächen bleiben dort unsichtbar; bei einer Anfrage leuchten nur die referenzierten Notes.

Mehr Details: [`RUNTIME-CONTROLS-HONEYCOMB.md`](RUNTIME-CONTROLS-HONEYCOMB.md).

## Autonome Anreicherung

Der Worker arbeitet bewusst sequenziell:

1. Kandidatenpaar aus bestehenden Vektoren auswählen;
2. Beziehung durch Qwen mit festem JSON-Schema prüfen;
3. Edge als `staging` oder `rejected` im In-Memory-Graph ablegen;
4. optional kontrolliert recherchieren;
5. AI-THINK-Entwurf in die Schreibwarteschlange legen;
6. beim nächsten Persistenz-Flush atomar in Staging schreiben.

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

Der manuelle AI-THINK-Button bleibt vorhanden. Alternativ:

```bash
curl -X POST 'http://localhost:8090/api/enrich?async=1'
```

## HTTP-Endpunkte

| Methode | Pfad | Zweck |
|---|---|---|
| `GET` | `/api/status` | Gesamtstatus inklusive Ollama-Pool, GLPI-KB und Persistenzqueue |
| `GET` | `/api/graph` | vollständiger aktueller In-Memory-Graph |
| `GET` | `/api/analysis` | strukturelle Graphanalyse |
| `GET` | `/api/runtime-settings` | aktuelle Learning-, Thinking-, Filter- und View-Einstellungen |
| `PUT` | `/api/runtime-settings` | Laufzeiteinstellungen ändern und gebündelt persistieren |
| `GET` | `/api/categories` | verfügbare Note-Kategorien mit Anzahl |
| `GET` | `/api/stream` | SSE-Aktivitätsstrom |
| `POST` | `/api/query` | programmatische Wissensanfrage; in der Fullscreen-UI verborgen |
| `POST` | `/api/events` | optionale Agent-/KB-Telemetrie |
| `POST` | `/api/reindex` | lokaler Scan und Embedding-Abgleich |
| `POST` | `/api/enrich` | AI-THINK-Zyklus einplanen/ausführen |
| `POST` | `/api/glpi-kb/sync` | GLPI-KB manuell synchronisieren |
| `POST` | `/api/flush` | ausstehende Dateien und Graph sofort persistieren |

Mit `BRAIN_API_KEY` werden POST-Endpunkte über `Authorization: Bearer …` oder `X-Brain-Key` geschützt.

## Statusdiagnose

```bash
curl http://localhost:8090/api/status | jq
```

Wichtige Bereiche:

- `ollama_pool.nodes[]`: Health, Kompatibilität, Inflight, Requests, Fehler und mittlere Laufzeit;
- `glpi_kb`: letzter Sync, Dokumentanzahl, Pfad und Fehler;
- `persistence`: ausstehende Dateien, Dirty-Status, letzter Flush und Flush-Fehler;
- `enrich_*`: Zustand des autonomen AI-THINK-Workers.

## Validierung

```bash
go test ./...
go vet ./...
node --check internal/web/static/app.js
```