glpi-neuroforge-mega/README.md

GLPI NeuroForge Mega v1.4.0

Ein kontrolliertes Monorepo aus GLPI AI Agent, GLPI AI Knowledgebase und NeuroForge + SQAR. Ziel ist nicht ein untrennbarer Monolith, sondern eine gemeinsame Plattform mit klaren Zuständigkeiten, getrennten Credentials und nachvollziehbaren Failure-Modi.

Unified Graph Explorer (v1.4.0)

Das read-only Control Center visualisiert Runtime/Trust, Ticket-Evidence, Learning-Lineage, Research-Provenance, einen redigierten NeuroForge-Brain-Graph sowie einen reproduzierbaren Engineering-Graph aus Go-AST und Compose. Für Dateien/Symbole/Routen gibt es zusätzlich eine statische Change-Impact-/Blast-Radius-Sicht. 2D ist der operative Default; 3D ist ein optionaler, gebundener Explorer.

Der Agent stellt diese Daten ausschließlich über einen eigenen CONTROL_READ_TOKEN bereit. Ein optionales codebase-memory-mcp kann lokal für tiefere Developer-Analyse betrieben werden, ist aber keine Produktionsabhängigkeit. Siehe docs/UNIFIED-GRAPH.md und docs/CODEBASE-MEMORY-MCP.md.

Leitprinzipien

• Maximale Kontrolle: GLPI-Schreibregeln, Auto-Reply-Gates, Eskalation, Idempotenz und Audit bleiben im Agenten. NeuroForge liefert semantische Evidenz, entscheidet aber nicht über Sicherheits- oder Kommunikationsregeln.
• Maximale Effizienz: Chunk-Vektoren können zentral in NeuroForge/HNSW/Disk-PQ liegen; das NFVJ2 Vector Journal nutzt die integrierte SQAR-Kompression. Dokument-Updates werden batchweise synchronisiert.
• Maximale Transparenz: local, dual und neuroforge erlauben einen messbaren Cutover; Fehlerverhalten ist explizit fail-open oder fail-closed; das Control Center ist read-only.
• Human Governance: Maschinell erzeugte Research-Vorschläge dürfen ausschließlich ins KB-Staging. Produktiv wird Wissen erst nach menschlicher Freigabe.

Komponenten

Komponente	Aufgabe	Schreibrechte
services/agent	GLPI-Triage, Policies, Antworten, Eskalation, Hybrid-Reranking	GLPI nach vorhandenen Policy-Gates
services/knowledge	Knowledge Authoring, Suche, Staging, Review, Promotion	Knowledge-Dateien + Staging
platform/neuroforge	semantisches Gedächtnis, HNSW/Disk-PQ, Learning, Research, SQAR-Vector-Journal	eigenes Brain-Storage
services/control	Status, aktive Migrationsparameter, Links	keine; read-only
ollama	gemeinsamer lokaler Inference-Endpunkt	Modellcache

Schnellstart

cp .env.example .env
./scripts/generate-secrets.sh
# Werte in .env übernehmen und GLPI-Zugangsdaten setzen.

docker compose config
docker compose up -d --build
./scripts/status.sh

Standardmäßig bindet der Stack nur an 127.0.0.1:

• Control Center: http://127.0.0.1:8070
• GLPI Agent: http://127.0.0.1:8080
• Knowledgebase: http://127.0.0.1:8081
• NeuroForge: http://127.0.0.1:8090/admin
• Ollama: http://127.0.0.1:11434

Vor dem ersten produktiven Start bleiben in .env.example alle automatischen GLPI-Aktionen deaktiviert und DRY_RUN=true.

Kontrollierter Vektor-Cutover

KNOWLEDGE_VECTOR_BACKEND kennt drei Modi:

• local: ursprüngliches Verhalten; Chunk-Vektoren bleiben im lokalen Agent-Snapshot.
• dual: lokale Vektoren bleiben maßgeblich und werden zusätzlich nach NeuroForge gespiegelt. Das ist der empfohlene Beobachtungsmodus.
• neuroforge: NeuroForge ist für Chunk-Vektor-Persistenz und semantische Kandidatensuche maßgeblich. Titel-, Text-, Metadaten- und GLPI-Policy-Signale bleiben lokal; der Agent führt weiterhin sein deterministisches Hybrid-Reranking aus.

Mit NEUROFORGE_FAIL_OPEN=true kann der Agent bei Backend-Ausfall lokale/lexikalische Evidenz verwenden. Mit false wird ein semantischer Backend-Fehler sichtbar blockierend behandelt.

Details: docs/MIGRATION-CUTOVER.md.

Kontrolliertes Lernen: erst Outcome, dann Wissen

Im produktionsnahen Standard (NEUROFORGE_CONTROLLED_LEARNING=true) werden rohe Chat-Eingaben und KI-Antworten nicht automatisch zu vertrauenswürdigem Langzeitwissen. Der Helpdesk-Lernpfad ist explizit menschlich gegated:

Ticket -> KI-Vorschlag -> Techniker bestätigt/korrigiert -> auditiertes Outcome -> NeuroForge lernt

Im Agent-Dashboard kann ein Antwortvorschlag als „KI-Antwort bestätigen“ oder „KI-Antwort korrigieren“ validiert werden. Jede Entscheidung wird lokal in ticket-outcomes.json mit Sync-Status gespeichert. Eine spätere Korrektur überschreibt die frühere Entscheidung nicht, sondern erzeugt eine neue Revision mit supersedes_id. Nur accepted und corrected dürfen den App-Key-geschützten NeuroForge-Endpunkt /api/v1/integrations/outcomes verwenden; NeuroForge weist die vertrauenswürdige Provenance serverseitig zu.

Vor der Hochstufung verifiziert der Agent außerdem, dass sich der GLPI-Ticketzustand seit dem analysierten Run nicht geändert hat. Ein veralteter Run darf nicht als Trusted Outcome gelernt werden.

Standardmäßig ist OUTCOME_LEARNING_FAIL_OPEN=false: Kann das bestätigte Outcome nicht nach NeuroForge synchronisiert werden, sieht der Techniker einen Fehler. Der lokale Audit-Eintrag bleibt mit sync_status=failed für einen kontrollierten Retry erhalten.

v1.3.0 schließt den Feedback-Loop: aktive, menschlich validierte Outcomes werden bei späteren ähnlichen Tickets als sekundäre Erfahrungs-Evidenz aus NeuroForge abgerufen. Sie dürfen die Antwortauswahl unterstützen oder ihr widersprechen, ersetzen aber niemals die Pflicht zu einem freigegebenen Knowledge-Artikel. Korrekturen superseden den alten NeuroForge-Memory atomar; die alte Revision bleibt auditierbar, ist aber nicht mehr retrieval-aktiv.

Ticket -> offizielle KB-Kandidaten
       -> aktive validierte Erfahrungen
       -> LLM-Auswahl unter Policy-Gates
       -> Techniker bestätigt/korrigiert
       -> NeuroForge Outcome Memory
       -> spätere Tickets profitieren davon

Die Wirkung kann read-only über POST /api/quality/replay gemessen werden. Der Replay-Runner berichtet u. a. Knowledge Recall@K/MRR, Outcome Recall@K/MRR und Fälle, in denen validierte Erfahrung einen Knowledge-Miss sichtbar macht. Beispiel: docs/QUALITY-REPLAY.md.

Details: docs/CONTROLLED-AUTONOMY.md.

Optionales SearXNG / kontrollierte Autonomie

SearXNG ist ein echtes, aber optionales Compose-Profil. Der normale Stack startet es nicht. Research und zeitgesteuerte Autonomie besitzen getrennte Schalter:

# .env: echten SEARXNG_SECRET setzen
./scripts/research-up.sh

research-up.sh startet SearXNG sowie NeuroForge mit Research/SearXNG aktiviert. NEUROFORGE_AUTONOMY_ENABLED bleibt davon unberührt und ist standardmäßig false. Damit sind drei Betriebsstufen möglich:

1. Research aus – keine Webrecherche.
2. Research an, Autonomy aus – Recherche kann explizit/manuell angestoßen werden.
3. Research an, Autonomy an – fällige Research-Goals dürfen zyklisch selbst recherchieren.

Web-Evidence erhält bewusst niedrigere Source-Trust-Werte als menschlich bestätigte GLPI-Outcomes. Unabhängige Quellen können bestehende Evidence über die vorhandene Corroboration-Logik stärken; produktive KB-Promotion bleibt trotzdem menschlich kontrolliert.

Research → Staging

Die Knowledgebase stellt einen getrennt authentifizierten Eingang bereit:

POST /api/integrations/staging
Authorization: Bearer <KB_INTEGRATION_TOKEN>

Dieser Endpunkt kann nur Staging-Entwürfe erzeugen. Er kann keine produktiven Artikel schreiben und erzwingt auto_reply=false. Beispiel:

export KB_INTEGRATION_TOKEN='...'
./scripts/propose-draft.sh proposal.json

Die Promotion bleibt ausschließlich beim normalen KB-Review-Workflow.

Obsidian / llm-wiki Export

Die Wissensbasis kann in zwei Sichten als Obsidian-kompatibler Vault exportiert werden:

• Knowledgebase: GET /api/export/obsidian – kanonische produktive JSON-Wissensbasis.
• Agent: GET /api/knowledge/export/obsidian – Live-Sicht inklusive synchronisierter GLPI-KB-Artikel und, sofern die GLPI-OpenAPI sie lesbar bereitstellt, KnowbaseItem_Item-Verknüpfungen.

Der Vault enthält YAML-Frontmatter, [[Wikilinks]], Wiki/Schema.md, Wiki/index.md, graph.json und ein Manifest. Beide UIs besitzen einen „⇩ Obsidian Export“-Button. CLI-Helfer:

./scripts/export-obsidian.sh kb ./knowledge-vault.zip
./scripts/export-obsidian.sh agent ./live-vault.zip

Details: docs/OBSIDIAN-EXPORT.md.

Wichtige Sicherheitsgrenzen

1. Der Agent erhält nur den NeuroForge App Key, niemals den Admin-Token.
2. NeuroForge erhält keine GLPI-Credentials.
3. Das Control Center besitzt keine Admin-/Editor-Credentials.
4. KB-Health ist ohne Editor-Credentials probe-fähig; alle Editor-Funktionen bleiben Basic-Auth-geschützt.
5. Research-Vorschläge haben einen separaten KB_INTEGRATION_TOKEN und landen ausschließlich im Staging.
6. runs.jsonl, State/Idempotenz, Policy-Gates und GLPI-Aktionen werden nicht in lernendes Memory verschoben.

Siehe docs/CONTROL-MATRIX.md, docs/CONTROL-CENTER.md und docs/ARCHITECTURE.md.

Validierung

./scripts/validate.sh
cd services/agent && go test -race ./internal/knowledge
cd ../../platform/neuroforge && go test -race ./internal/httpapi ./internal/store

Die importierten GLPI-Projekte wurden im Mega-Repo auf Go 1.23 normalisiert. Die komplette Testbasis läuft damit in der bereitgestellten Umgebung. Die ursprünglichen Quellarchive bleiben davon unberührt.

Für Qualitätsmessungen gegen historische Fälle:

python3 scripts/quality-replay.py docs/QUALITY-REPLAY-example.json --url http://127.0.0.1:8080

Bewusst begrenzte Autonomie

Auch bei aktivierter Research-Autonomie veröffentlicht NeuroForge nicht selbstständig in die produktive Knowledgebase. Der technische Draft-Ingress ist vorhanden, aber der Übergang von einem konkreten Research-Run zu einem KB-Draft soll über einen expliziten Workflow/Job erfolgen. Das ist eine Governance-Entscheidung, kein fehlender Schreibweg.