Init

2026-08-26 18:34:41 +02:00
parent 3d8ffe6dfd
commit a6bc71fb3a
514 changed files with 199925 additions and 1 deletions
@@ -0,0 +1,202 @@
+# Architektur
+
+## Zielbild
+
+```text
+                           ┌─────────────────────┐
+                           │       GLPI          │
+                           └─────────┬───────────┘
+                                     │
+                                     ▼
+                           ┌─────────────────────┐
+                           │   GLPI AI Agent     │
+                           │ policies / actions  │
+                           └──────┬───────┬──────┘
+                                  │       │ events
+                   semantic query │       └──────────────┐
+                                  ▼                      ▼
+                     ┌─────────────────────┐      ┌──────────────┐
+                     │ NeuroForge Brain    │      │ Control      │
+                     │ HNSW / Disk-PQ      │      │ read-only    │
+                     │ NFVJ2 + SQAR        │      └──────────────┘
+                     │ memory / research   │
+                     │ validated outcomes  │
+                     └─────────┬───────────┘
+                               │ draft proposal only
+                               ▼
+                     ┌─────────────────────┐
+                     │ Knowledge Staging   │
+                     │ human review        │
+                     └─────────┬───────────┘
+                               │ promote
+                               ▼
+                     ┌─────────────────────┐
+                     │ Production KB       │
+                     └─────────┬───────────┘
+                               │ shared files / incremental scan
+                               └──────────────► Agent
+```
+
+## Verantwortungsgrenzen
+
+### GLPI AI Agent
+
+Bleibt die autoritative Schicht für:
+
+- Kategorien- und Prioritätslogik
+- Eskalation
+- Auto-Reply-Gates
+- GLPI-Schreiboperationen
+- Dry-Run
+- Idempotenz und Ticket-State
+- Hybrid-Scoring nach semantischer Kandidatensuche
+- Quellen-Allowlisten
+
+NeuroForge darf diese Regeln weder verändern noch umgehen.
+
+### NeuroForge
+
+Ist die autoritative Schicht für zentral externalisierte Chunk-Vektoren:
+
+- namespace-isolierte Knowledge-Chunks
+- HNSW-/Disk-PQ-Kandidatensuche
+- Vector Journal NFVJ2
+- SQAR-Kompression des Vector Journals
+- Brain-/Knowledge-Events
+- eigenes Learning/Research
+
+Die neue Integrations-API ist mit dem App Key geschützt und enthält bewusst keine Admin-Funktionen.
+
+### Knowledgebase
+
+Bleibt die Governance-Schicht:
+
+- kanonische JSON-Artikel
+- Editor
+- Suche
+- Staging
+- Backup
+- Review
+- Promotion
+
+Maschinelle Integrationen können nur Staging-Entwürfe ablegen.
+
+## Datenfluss für Retrieval
+
+```text
+Tickettext
+  -> Embedding-Profil des Agenten
+  -> NeuroForge namespace search
+  -> Top-N semantische Kandidaten
+  -> Agent ordnet Treffer Dokumenten zu
+  -> exakte lokale Titel-/Keyword-/Kategorie-/Lexikal-Signale
+  -> deterministischer Hybrid-Score
+  -> bestehende GLPI Policy-Gates
+  -> ggf. Aktion
+```
+
+Damit bleibt ANN ein Kandidatengenerator, nicht die finale Policy-Entscheidung.
+
+## Persistenz
+
+### Agent
+
+- lokale Knowledge-Metadaten und Chunks
+- Titelvektoren
+- im `local`/`dual`-Modus auch Chunk-Vektoren
+- Audit-/Run-/State-Dateien
+
+### NeuroForge
+
+- Memory/WAL/Segments
+- HNSW bzw. Disk-PQ
+- NFVJ2 Vector Journal
+- SQAR nur auf geeigneten Vektorblöcken
+
+### Knowledgebase
+
+- `knowledge/` produktiv
+- `staging/` ungeprüft
+- `backups/` Recovery
+
+## Konsistenzmodell
+
+Die JSON-Knowledgebase bleibt fachlich kanonisch. NeuroForge ist ein abgeleiteter semantischer Index. Dokument-IDs und Chunk-Indizes erzeugen deterministische NeuroForge-Memory-IDs. Änderungen ersetzen Chunks batchweise; entfernte Chunks werden entfernt. Dadurch kann ein kompletter Neuaufbau aus der Knowledgebase erfolgen.
+
+## Eventing
+
+Die vorhandenen `brainactivity`-Clients zeigen jetzt auf:
+
+```text
+POST /api/v1/integrations/events
+```
+
+Diese Events sind Telemetrie/Audit, keine Policy-Eingaben. Beispiele sind `knowledge.search` sowie Synchronisationsereignisse.
+
+
+## Kontrolliertes Lernmodell (v1.2.0)
+
+### Human Outcome Gate
+
+```text
+Ticket -> AI proposal -> technician accept/correct
+                         |
+                         v
+                  immutable local audit
+                         | App Key
+                         v
+             /api/v1/integrations/outcomes
+                         |
+                         v
+          trusted semantic outcome memory
+```
+
+Der Agent bestimmt nicht selbst die vertrauenswürdige Provenance. NeuroForge akzeptiert über diesen Pfad ausschließlich `accepted` und `corrected` und setzt `glpi.outcome.*` serverseitig. Eine spätere Korrektur wird als neue Outcome-Version mit `supersedes_id` geführt.
+
+### Optionaler Research-Layer
+
+```text
+             [compose profile: research]
+                      SearXNG
+                         |
+                         v
+Goal/manual research -> Search -> Fetch -> Evidence
+                                      |
+                                      v
+                         provenance + dedup +
+                         independent corroboration
+                                      |
+                                      v
+                              NeuroForge Memory
+                                      |
+                                      v
+                              KB staging only
+```
+
+Research-Infrastruktur und zeitgesteuerte Autonomie sind getrennt. `NEUROFORGE_AUTONOMY_ENABLED=false` verhindert selbstlaufende Goal-Cycles auch dann, wenn SearXNG und manuelles Research aktiv sind.
+
+## v1.3: Closed Outcome Feedback Loop
+
+Menschlich validierte Helpdesk-Erfahrung besitzt einen eigenen, schmalen Retrieval-Pfad:
+
+```text
+Agent ticket query
+   |--------------------------|
+   v                          v
+Knowledge namespace      Validated outcomes
+HNSW/PQ + hybrid         active accepted/corrected only
+   |                          |
+   +------------+-------------+
+                v
+          Reply selection
+                |
+      Knowledge ID allow-list
+                |
+          Policy gates / GLPI
+```
+
+Die beiden Evidenzklassen werden absichtlich nicht vermischt. Outcome-Memories liegen im NeuroForge-Brain und sind Trust-/Revision-basiert; Knowledge bleibt die veröffentlichte Autorität. Bei Korrekturen bleiben alte Memories auditierbar, wechseln aber auf `superseded` und sind nicht mehr search-active.
+
+Für source-begrenzte Exact-Fallbacks hält der Store einen rebuildbaren In-Memory-Index `Provenance.Source -> Memory IDs`. Damit wächst der Fallback mit der betreffenden Integration/Source statt mit dem gesamten Memory-Katalog. HNSW/Disk-PQ bleiben globale Kandidatenindizes.
+
+Die Qualitätsmessung ist vom Schreibpfad getrennt: `/api/quality/replay` ist read-only und evaluiert live die aktuelle Knowledge-/Outcome-Retrieval-Konfiguration gegen einen bereitgestellten historischen Fallkorpus.