glpi-neural-brain/README.md

# 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.
- Drei Visualisierungen: Neural-Brain, gleichmäßige 3D-Honeycomb-Wabe und semantische Constellation-Ansicht mit Themensternen.
- Persistierbarer **ECO**-Modus für schwächere Systeme sowie weiche Node-, Edge- und Ansichtsübergänge ohne sichtbaren Komplett-Reload.
- Laufzeitsteuerung für Learning und Thinking sowie drei einfache, exakte `source`-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`.
- Optionaler mathematischer Knowledge-Nachbarschaftsgraph aus bereits vorhandenen Embeddings (`semantic_neighbor`): LSH + Cosine + mutual k-NN/local scaling, ohne zusätzlichen Modellaufruf; periodische Re-Evaluierung und sanfte 3D-Entzerrung dichter Wolken sind getrennt steuerbar.
- Mehrstufiger AI-THINK-Worker: Relation Thinking, quellengebundene Wissenskonsolidierung, Recherche offener Punkte und Knowledge-Synthesis mit artikeltypspezifischer Tiefe, mathematischem CPU-Pre-Review sowie getrenntem Claim-/Coverage-Review.
- Persistente **Autonomous-Research-Queue**: selbstständige Wissenslückensuche, externe Trigger, Leerlauf-/Budgetsteuerung und niedrig priorisierte Übergabe an den vorhandenen Ollama-Pool.
- Inkrementelle SQLite/WAL-Persistenz über `modernc.org/sqlite`: binäre Float32-Embeddings und standardmäßig alle fünf Minuten gebündelte Row-Updates.
- Separates **BRAIN ANALYSIS CENTER** mit persistenter Laufhistorie, exakten Node-/Edge-/Vektoränderungen, Similarity-/Confidence-Auswertung, Research-Ergebnissen und technischem Roh-Eventstream.

## 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. Artikelentwürfe erhalten zusätzlich `AI-Synthesis`; `text` und `answer` enthalten ausschließlich den fachlichen Artikel. Planung, Bewertung, Confidence, Quellen-IDs und Rechercheprotokolle werden separat unter `BRAIN_DATA_DIR/article-metadata/` gespeichert.


## Grounded Knowledge Synthesis

Verwandtes Wissen wird nicht direkt als Bewertungsbericht gespeichert. Die Artikelpipeline arbeitet nach **Adaptive Generate → Review**: Im `clustered`-Modus beginnt der Autor (z. B. Gemma) mit kohärenten internen KB-Quellen. SearXNG wird gezielt vorgeschaltet, wenn ein deterministischer Aktualitätsdetektor Versions-/Support-/CVE-/Patch-/Preis-/Live-Status erkennt, wenn der Planner für einen operationalen Artikel nur zwei kohärente interne Quellen findet, wenn dem Entwurf ausführbare Schritte/Validierung fehlen oder wenn das Modell selbst eine konkrete Evidenzlücke meldet. Erst danach prüft ein getrenntes Reviewer-Modell den sichtbaren Text Claim für Claim und kann weitere gezielte Nachrecherche auslösen. Frisch recherchierte Webvolltexte bleiben zunächst nur im Evidence-Store; nur tatsächlich vom Reviewer verwendete Quellen dürfen die interne Mindestquellenregel ergänzen und als Graph-Evidenz materialisiert werden.

Details: [`KNOWLEDGE-SYNTHESIS.md`](KNOWLEDGE-SYNTHESIS.md), [`GENERATE-THEN-REVIEW.md`](GENERATE-THEN-REVIEW.md) und [`ADAPTIVE-ARTICLE-WORKFLOW.md`](ADAPTIVE-ARTICLE-WORKFLOW.md).

v8 ergänzt einen modellfreien CPU-/Agent-Quality-Layer und eine langsame semantische Layout-Relaxation. Details: [`ARTICLE-QUALITY-CPU-V8.md`](ARTICLE-QUALITY-CPU-V8.md).

v10 haertet Relationsrecherche, Autonomous-Queue, Artikeltyp-Routing und die von Learning entkoppelte Vector-Maintenance. Details: [`WORKFLOW-INTEGRITY-V10.md`](WORKFLOW-INTEGRITY-V10.md).

v12 korrigiert den modellfreien Artikel-Quality-Gate-Deadlock aus analysis(21): lexikalisches Evidence-Alignment ist diagnostisch, harte Struktur-/Dichte-Gates bleiben erhalten und semantisches Grounding erfolgt im Qwen-Review. Details: [`ARTICLE-QUALITY-GATE-V12.md`](ARTICLE-QUALITY-GATE-V12.md).

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

Technisches Analyse-Dashboard: `http://localhost:8090/analysis.html`

Das Analyse-Dashboard ist von der animierten Gehirnansicht getrennt. Es bewertet Läufe als positives Ergebnis, Aktualisierung, Bereinigung, Prüfung ohne Übernahme oder Fehler und zeigt die konkret betroffenen Node-, Edge- und Vektor-IDs. Die Historie wird in `graph.db` aufgezeichnet und beginnt ab Installation dieser Version. Details: [`ANALYSIS-DASHBOARD.md`](ANALYSIS-DASHBOARD.md).

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

## SQLite/WAL-Persistenz und Vorberechnung

```env
BRAIN_PERSIST_INTERVAL=5m
```

Der Live-Graph liegt im Arbeitsspeicher. Dauerhaft gespeichert werden nur geänderte Zeilen in `BRAIN_DATA_DIR/graph.db`:

1. AI-THINK-, Metadaten- und Cache-Dateien werden atomar geschrieben;
2. danach folgen geänderte Nodes, Edges und Vektoren in einer SQLite-Transaktion;
3. Embeddings liegen binär als `float32`-BLOBs vor;
4. unveränderte KB-Scans verursachen keine erneuten Graphwrites.

Manueller Flush:

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

Ein auf einem leistungsfähigen System vorberechneter Graph kann kompakt exportiert und auf ein System mit identischen Dokument-IDs und demselben Embedding-Modell kopiert werden:

```bash
curl -fsS http://localhost:8090/api/state/export -o graph.db
```

Mehr Details: [`PERSISTENCE.md`](PERSISTENCE.md) und [`SQLITE-STORAGE.md`](SQLITE-STORAGE.md).

### Experiment: mathematische semantische Kanten

Mit `BRAIN_VECTOR_GRAPH_ENABLED=true` kann direkt nach dem normalen Embedding-Schritt eine rein mathematische Knowledge↔Knowledge-Schicht erzeugt werden. Sie verwendet bereits gespeicherte Embeddings und erzeugt `semantic_neighbor` statt `same_topic`, weil Vektornähe kein fachlicher Beweis ist. Edge-Berechnung und optionales 3D-Layout verursachen keinen zusätzlichen Ollama-/LLM-/Embedding-Aufruf. Ein optionaler Orphan-Second-Pass kann verbleibende isolierte Knowledge-Nodes konservativ gegen den vollständigen Vectorbestand prüfen. Mit `BRAIN_VECTOR_GRAPH_AGENT_OFFLOAD=true` darf ein integrierter Source Agent diesen CPU-Job übernehmen; das Brain validiert und persistiert weiterhin selbst. AI-THINK kann anschließend zuerst diese mathematischen Kandidaten bewerten, statt erneut den gesamten Vektorraum zu durchsuchen. Details: [`VECTOR-GRAPH-EXPERIMENT.md`](VECTOR-GRAPH-EXPERIMENT.md) und [`VECTOR-GRAPH-AGENT-OFFLOAD-V3.md`](VECTOR-GRAPH-AGENT-OFFLOAD-V3.md).

## Laufzeitsteuerung, Visualisierungen und Performance

Die untere Steuerleiste enthält direkte Schalter für **LEARNING**, **THINKING**, **NEURAL**, **HONEYCOMB**, **CONSTELLATION** und **ECO**. 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** werden ausschließlich die exakten Werte des JSON-Feldes `source` ausgewählt. Es gibt keine Kategoriefilter, keine technische `origin`-Aliasauflösung und keine Schnittmenge aus Environment und WebUI mehr.

- **Lernen**: Nur Nodes mit exakt passendem `source` erhalten neue Embeddings und dürfen bei semantischen Abfragen verwendet werden.
- **Anzeige**: Nur Nodes mit exakt passendem `source` werden gerendert; direkt verbundene Kategorie-, Quellen- und Konzept-Nodes bleiben als visuelle Taxonomie sichtbar.
- **Thinking**: Nur Nodes und explizit mit einer Quelle versehene Webbelege mit exakt passendem `source` dürfen neue Relationen und Artikel speisen.

Mehrere ausgewählte Quellen verwenden ODER-Semantik. Eine leere Liste bedeutet „alle Quellen“. Der Vergleich ist nach dem Entfernen äußerer Leerzeichen **case-sensitiv und exakt**:

```text
source: "internal-category"  passt zu  internal-category
source: "internal-category"  passt nicht zu  Internal-Category
source: "GLPI Knowledge Base" passt nicht zu  glpi-kb
```

Der GLPI-Quellenname stammt ausschließlich aus:

```env
GLPI_KB_SOURCE=GLPI Knowledge Base
```

Dieser Wert wird in der WebUI immer als Auswahl angeboten, auch wenn GLPI noch nicht synchronisiert wurde oder aktuell 0 Beiträge vorhanden sind.

Die folgenden Environment-Variablen sind nur Startwerte, wenn noch keine neue versionierte `runtime-settings.json` existiert. Danach ist die WebUI-Auswahl die einzige aktive Konfiguration; es gibt keine zusätzliche Environment-Obergrenze:

```env
BRAIN_LEARNING_ENABLED=true
BRAIN_THINKING_ENABLED=true

# Exakte Werte des KB-JSON-Feldes source; leer = alle
BRAIN_LEARNING_SOURCES=
BRAIN_DISPLAY_SOURCES=
BRAIN_THINKING_SOURCES=

BRAIN_DEFAULT_VIEW=neural  # neural | honeycomb | constellation
BRAIN_MAX_DISPLAY_NODES=0  # 0 = unbegrenzt; alternativ z. B. 5000
BRAIN_LOW_POWER_MODE=false

# v11: aggressiver Throughput-/Benchmark-Modus. CPU leer = runtime.NumCPU().
BRAIN_SPEED_MODE=false
BRAIN_SPEED_CPU_TASKS=
BRAIN_SPEED_GPU_TASKS=4
```

Alte `learning_categories`, `display_categories`, `thinking_categories` und frühere unversionierte Source-Filter werden beim ersten Start dieser Version bewusst ignoriert. Schalter, Ansicht und Performancewerte bleiben erhalten. Beim nächsten Speichern schreibt die WebUI `source_filter_version: 1`. `graph.db` muss dafür nicht gelöscht werden.

Die Ansichten erfüllen unterschiedliche Aufgaben:

- **Neural** zeigt das lebende semantische Netz mit LOD, Cortex, Synapsen und Partikeln.
- **Honeycomb** rendert `knowledge`, `ai-think` und `external` gleichmäßig in einer 3D-Gehirnwabe. Reguläre Edges und Cortex-Flächen bleiben dort unsichtbar.
- **Constellation** ordnet Wissenselemente als Themensterne um semantische Zentren an. Dezente Bahnen und aggregierte Themenverbindungen machen Fachgebiete und Übergänge leichter lesbar als ein dichtes Gesamtnetz.

Der **ECO**-Schalter begrenzt die Ausgabe auf ungefähr 30 FPS, reduziert die Device-Pixel-Ratio, teure Gradienten, Hintergrundsterne, gleichzeitig sichtbare inaktive Edges, Partikel und Wolken. Aktivierte Nodes, SearXNG-Animationen, Themenzentren und Übergänge bleiben sichtbar. Das ist zusätzlich zum GPU-Node-Limit; der ECO-Modus entfernt keine Wissenselemente.

Graphupdates verändern vorhandene Node-Objekte und Positionen in-place. Neue Elemente blenden ein, entfernte Elemente blenden aus, Ansichtswechsel morphen zwischen den Koordinatenräumen. Unveränderte Snapshots werden übersprungen und reine Edgeupdates lösen keinen vollständigen Layout-Neuaufbau aus.

Mehr Details: [`SOURCE-ONLY-FILTERS.md`](SOURCE-ONLY-FILTERS.md), [`VISUALIZATION-PERFORMANCE.md`](VISUALIZATION-PERFORMANCE.md) und [`RUNTIME-CONTROLS-HONEYCOMB.md`](RUNTIME-CONTROLS-HONEYCOMB.md).

## Autonomous Research: selbstständige Wissensanreicherung

Die Webrecherche ist nicht mehr an einen einzelnen AI-THINK-Artikelversuch gebunden. Ein eigener Opportunity-Scanner bewertet den Graphen regelmäßig auf Widersprüche, fehlende externe Evidenz, Alter, Zentralität und schwache Verknüpfung. Qwen zerlegt geeignete Kandidaten in konkrete Forschungsfragen sowie deutsche und englische SearXNG-Queries.

Aufgaben landen zuerst persistent in `graph.db`. Ein Low-Priority-Worker least genau eine Aufgabe, prüft Leerlauf und Tagesbudget und verwendet danach die bestehende iterative SearXNG-/Volltext-/Evidenzpipeline. SearXNG-Suchen, Volltextabrufe und Ollama-Aufrufe teilen jetzt zusätzlich eine gemeinsame begrenzte Work-Queue. Semantisch äquivalente Research-Intents werden über Embeddings erkannt: läuft bereits eine gleichbedeutende Recherche, wartet der zweite Auftrag auf ihr Ergebnis; kürzlich abgeschlossene Evidenz kann ohne erneuten Webabruf wiederverwendet werden. Deutsche und englische Query-Varianten innerhalb derselben Forschungsfrage bleiben ausdrücklich erhalten.

```env
BRAIN_AUTONOMOUS_RESEARCH_ENABLED=false
BRAIN_AUTONOMOUS_RESEARCH_IDLE_ONLY=true
BRAIN_AUTONOMOUS_RESEARCH_INTERVAL=30m
BRAIN_AUTONOMOUS_RESEARCH_TASKS_PER_CYCLE=1
BRAIN_AUTONOMOUS_RESEARCH_MAX_TASKS_PER_DAY=12
BRAIN_AUTONOMOUS_RESEARCH_MAX_QUERIES_PER_TASK=6
BRAIN_AUTONOMOUS_RESEARCH_MAX_PAGES_PER_TASK=8
BRAIN_AUTONOMOUS_RESEARCH_MAX_ROUNDS=3
BRAIN_AUTONOMOUS_RESEARCH_MIN_PRIORITY=0.65
BRAIN_AUTONOMOUS_RESEARCH_COOLDOWN=168h
BRAIN_AUTONOMOUS_RESEARCH_LEASE=45m
BRAIN_AUTONOMOUS_RESEARCH_MAX_ATTEMPTS=3
BRAIN_AUTONOMOUS_RESEARCH_QUERY_TRIGGERS=true
BRAIN_AUTONOMOUS_RESEARCH_OPPORTUNITY_LIMIT=8
```

Der Agent oder andere Systeme können über `POST /api/research/tasks` explizit Aufgaben einreihen. Die Eventtypen `knowledge.answer_insufficient`, `knowledge.search.empty` und `agent.answer.uncertain` erzeugen über `/api/events` ebenfalls eine priorisierte Aufgabe. Die WebUI zeigt Queue, Status, Evidenzzahl und Versuche und bietet manuelles Einreihen, Graphanalyse, Queue-Wakeup sowie Abbruch wartender Aufgaben.
Die aktualisierten Integrationspatches unter `integrations/agent/` und `integrations/knowledgebase/` senden bei einer Suche ohne Treffer automatisch `knowledge.search.empty`; die Telemetrie bleibt asynchron und fail-open.

Akzeptierte Webbelege werden automatisch gelernt und verknüpft. Neue oder überarbeitete Artikel bleiben weiterhin ausschließlich im AI-Staging und benötigen eine manuelle Freigabe.

Details: [`AUTONOMOUS-RESEARCH.md`](AUTONOMOUS-RESEARCH.md).

## Speed Mode v11

Mit `BRAIN_SPEED_MODE=true` entfernt das Brain kuenstliche Pacing-Pausen und erhoeht CPU-/GPU-Parallelitaet zur Laufzeit. `BRAIN_SPEED_CPU_TASKS` steuert Compute-/Vector-Worker, `BRAIN_SPEED_GPU_TASKS` das InFlight-Limit **je Ollama-Node**. Der Vector-Graph parallelisiert im Speed-Modus auch seine internen per-Node LSH/Cosine-Phasen. Eco und Speed sind gegenseitig exklusiv. Safety-/Quality-Gates, Fehler-Cooldowns, Timeouts, Graph-/SQLite-Locks, Autonomous-Tagesbudget und Docker-Controller-Policy bleiben aktiv. Details: [`SPEED-MODE-V11.md`](SPEED-MODE-V11.md).

## Autonome Anreicherung

Der Worker arbeitet bewusst sequenziell, trennt aber jetzt zwei Aufgaben:

1. Kandidatenpaar aus bestehenden Vektoren auswählen;
2. **Relation Thinking** bewertet ausschließlich die Beziehung und erzeugt eine Edge oder verwirft sie;
3. bei einer bestätigten Relation werden drei bis acht verwandte interne Quellen gesammelt;
4. ein Planungsaufruf entscheidet `create`, `update`, `merge` oder `skip` und formuliert Research-Themen;
5. im adaptiven Cluster-Modus wird SearXNG nur bei Aktualitäts-/Evidenzbedarf genutzt; im `always`-Modus sammelt es weiterhin passende Volltexte als Materialpool;
6. `BRAIN_ARTICLE_SYNTHESIS_MODEL` schreibt den vollständigen Artikel;
7. `BRAIN_ARTICLE_REVIEW_MODEL` prüft den fertigen Text Claim für Claim und kann eine gezielte Research-/Rewrite-Runde auslösen;
8. nur der akzeptierte Artikel landet als `AI-THINK` / `AI-Staging` / `AI-Synthesis` im Staging;
9. der In-Memory-Graph sieht den Entwurf sofort, die Datei wird beim nächsten gebündelten Persistenz-Flush atomar geschrieben.

Qualitätsregeln verhindern reine AI-THINK-Ketten: standardmäßig mindestens drei produktive Quellen, mindestens 70 Prozent Produktionswissen und maximal Generierungstiefe zwei.

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

BRAIN_ARTICLE_SYNTHESIS_ENABLED=true
BRAIN_ARTICLE_LANGUAGE=de-DE
BRAIN_ARTICLE_SYNTHESIS_MODEL=gemma3:12b
BRAIN_ARTICLE_REVIEW_MODEL=qwen3:8b
BRAIN_ARTICLE_REVIEW_REPAIR_ROUNDS=1
BRAIN_ARTICLE_MIN_SOURCES=3
BRAIN_ARTICLE_MAX_SOURCES=8
BRAIN_ARTICLE_MIN_PRODUCTION_RATIO=0.70
BRAIN_ARTICLE_MAX_GENERATION_DEPTH=2
BRAIN_ARTICLE_MIN_CONFIDENCE=0.74

# offene, recall-orientierte Recherche
BRAIN_ARTICLE_RESEARCH_RESULTS=12
BRAIN_ARTICLE_RESEARCH_FETCH_RESULTS=6
BRAIN_ARTICLE_RESEARCH_EXPLORATION_RESULTS=3
BRAIN_ARTICLE_RESEARCH_PREFETCH_MIN_RELEVANCE=0.25
BRAIN_ARTICLE_RESEARCH_MIN_RELEVANCE=0.55
BRAIN_ARTICLE_RESEARCH_MIN_QUALITY=0.35

# gemeinsame Research/Ollama-Queue und semantische Deduplizierung
BRAIN_RESEARCH_OLLAMA_MAX_INFLIGHT=2
BRAIN_RESEARCH_OLLAMA_QUEUE_SIZE=64
BRAIN_RESEARCH_DEDUPE_THRESHOLD=0.92
BRAIN_RESEARCH_DEDUPE_TTL=45m
```

Details: [`KNOWLEDGE-SYNTHESIS.md`](KNOWLEDGE-SYNTHESIS.md).

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/analysis/dashboard` | detaillierte aktuelle Analyse, Laufhistorie, Zeitreihe und konkretes Änderungsjournal |
| `GET` | `/api/analysis/export` | vollständige Analyse als formatiertes JSON exportieren |
| `GET` | `/api/runtime-settings` | aktuelle Learning-, Thinking-, exakte Source- und View-Einstellungen |
| `PUT` | `/api/runtime-settings` | Laufzeiteinstellungen ändern und gebündelt persistieren |
| `GET` | `/api/sources` | exakte `source`-Werte mit Anzahl; enthält immer `GLPI_KB_SOURCE` |
| `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 geänderte SQLite-Zeilen sofort persistieren |
| `GET` | `/api/state/export` | kompakte, konsistente `graph.db` exportieren |
| `GET` | `/api/research/tasks` | persistente autonome Research-Queue und Workerstatus |
| `POST` | `/api/research/tasks` | externe oder manuelle Rechercheaufgabe asynchron einreihen |
| `POST` | `/api/research/tasks/{id}/cancel` | wartende, zurückgestellte oder reservierte Aufgabe abbrechen |
| `POST` | `/api/research/autonomous/scan` | Graph sofort nach Wissenslücken analysieren |
| `POST` | `/api/research/autonomous/run` | wartende Queue ohne Umgehung der Kapazitätsregeln wecken |

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;
- `graph_storage`: SQLite-/WAL-Größe, Vector-Bytes, Row-Anzahl und ausstehende Änderungen;
- `enrich_*`: Zustand des AI-THINK-Workers;
- `autonomous_research`: Queue-Zähler, laufende Aufgabe, Budgetparameter, letzte Fehler sowie gelernte Evidenz und erzeugte Staging-Artikel;
- `relations_created`, `articles_created`, `articles_skipped`: getrennte Relation- und Artikelergebnisse.

## Validierung

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

## Sichtbare SearXNG-Recherche

SearXNG-Suchen werden als eigenständige Aktivität visualisiert. Scanringe markieren die laufende Suche. Im adaptiven Artikelpfad werden gefundene Volltexte zunächst nur im Evidence-Store gespeichert; externe Graph-Nodes erscheinen erst, wenn der finale Reviewer die Quelle tatsächlich für einen unterstützten Claim verwendet. Relations- und Autonomous-Research können weiterhin eigene Research-Nodes erzeugen.

Unter **FILTER → SearXNG-Diagnose** kann eine direkte Testsuche ausgeführt werden. Diese umgeht die fachliche Qwen-Entscheidung, verändert den Graphen nicht und zeigt eindeutig:

- die tatsächlich verwendete Basis-URL,
- HTTP-Status und Content-Type,
- Trefferzahl und Laufzeit,
- DNS-, Netzwerk-, TLS-, HTTP- und JSON-Fehler,
- bei Fehlern den Antwortausschnitt von SearXNG oder Reverse Proxy.

Die Artikelrecherche arbeitet ohne `site:`-Filter und ist im Cluster/Fast-Modus standardmäßig adaptiv: interne Quellen/Gemma zuerst, SearXNG nur bei Aktualitäts- oder konkretem Evidenzbedarf, anschließend Claim-Review und ggf. gezielte Repair-Recherche. Im Analyse-Center zeigt der Ollama-Status aktive/wartende Einträge der gemeinsamen Research/Ollama-Queue sowie die Verfügbarkeit von Autor- und Reviewer-Modell. Die API-Endpunkte sind `GET /api/research/status` und `POST /api/research/test`. Details stehen in `SEARXNG-VISUALIZATION.md`, `GENERATE-THEN-REVIEW.md` und `ADAPTIVE-ARTICLE-WORKFLOW.md`.

## Cluster/Fast-Verarbeitungsmodus

Für große Wissensgraphen kann neben dem bisherigen präzisen Vollscan der Modus `BRAIN_PROCESSING_MODE=clustered` verwendet werden. Er nutzt Semantic Hashing zur Kandidatenvorsortierung, berechnet exakte Cosine-Nähe nur für eine kleine Top-K-Shortlist, bündelt thematisch kompatible Relationen zu gemeinsamen Artikeljobs, nutzt adaptive statt obligatorischer Webrecherche und materialisiert Webquellen erst nach Reviewer-Grounding. Der finale Claim-Review bleibt erhalten. Details: `CLUSTER-FAST-MODE.md` und `ADAPTIVE-ARTICLE-WORKFLOW.md`.

## Integrated distributed Source Agents

The project can now run the exact same binary/image as either the full Brain or a lightweight source poller:

```env
BRAIN_MODE=brain
```

or:

```env
BRAIN_MODE=agent
BRAIN_AGENT_BRAIN_URL=https://brain.example.org
BRAIN_AGENT_ID=security-news-01
BRAIN_AGENT_TOKEN=brain_agent_...
```

Create Agents and RSS/Atom/sitemap/Web polling tasks under `/source-agents.html`. Set `BRAIN_PUBLIC_URL` on the Brain to an address the Agent can actually reach; do not copy a browser-side `127.0.0.1`/`localhost` URL into a separate Agent container. The Agent exposes a small diagnostics UI on `/` and detailed connection state on `/api/status`; the example compose publishes it with `BRAIN_AGENT_PORT` (default `8092`). Incoming documents first enter a persistent Source Inbox and are classified against the local KB; adaptive article research searches this Inbox before falling back to SearXNG. Discovered documents are not materialized as graph knowledge until a reviewer actually uses them to ground a supported claim. See `SOURCE-AGENT-MODE.md` for the API, security model and deployment example.

Source Agents can additionally advertise a `vector_graph` CPU capability. With `BRAIN_VECTOR_GRAPH_AGENT_OFFLOAD=true`, the Brain can stream already existing embeddings to such an Agent for deterministic LSH/k-NN/Cosine/local-scaling calculation. This compute path performs no Chat or Embed call on the Agent and works even when the Agent has no source polling task. `BRAIN_VECTOR_GRAPH_AGENT_REQUIRED=false` keeps a safe local CPU fallback.

### Production Readiness v1

Der aktuelle Stand enthält einen Bootstrap-Gate, kausale Workflow-Mutationsmessung, append-only Audit-Events, Source-Inbox/Graph-Reconciliation und einen Knowledge-Manifest-Fast-Path. Für große Knowledge-Bestände ist der Default für `BRAIN_SCAN_INTERVAL` nun `5m`; zusätzlich verifiziert `BRAIN_KNOWLEDGE_FULL_VERIFY_INTERVAL=6h` den vollständigen Dateiinhalt periodisch. Details: `CHANGELOG-PRODUCTION-READINESS.md` und `VALIDATION-PRODUCTION-READINESS.md`.

## Host-Docker Controller (v9, opt-in)

Ein vertrauenswürdiger Source Agent kann zusätzlich als zentral gesteuerter Docker-Controller dienen. Der Controller ist standardmäßig ausgeschaltet und der normale Agent mountet **keinen** Docker Socket. Nach explizitem Opt-in kann das Brain typisierte Container-/Network-/Volume-/Compose-Jobs verwalten und vorab freigegebene Profile autonom für Evidence-Zweitprüfung, Health-Recovery, Compute-Kapazität und Smoke-Tests verwenden. Ein globaler Hauptschalter und Emergency Stop bleiben im Brain-Dashboard verfügbar.

Wegen der hohen Privilegien von Docker.sock gibt es keinen freien Docker-Exec-/Shell-Kanal für das Brain oder ein Modell. Details, Threat Model und Deployment: `DOCKER-CONTROLLER-V9.md`.