Publish API container to GHCR + Observability & Federation architecture

CHANGELOG.md

@@ -8,10 +8,15 @@ Alle nennenswerten Aenderungen an diesem Projekt werden in dieser Datei festgeha
 
 - GHCR-Publish-Workflow fuer das API-Container-Image bei Release-Tags und manuellen Tag-Backfills.
 - Build-Argument fuer `BEYOND_AI_VERSION`, damit Container und Health-Endpoint dieselbe Release-Version tragen.
+- Neues Architekturmodul `observability/` fuer den Qualitaets-Layer aus Detection Integrity, Data Trust, Service Health und Business Impact.
+- Neues Architekturmodul `federation/` fuer das foederative Drei-Schichtenmodell aus Public, Federated und Internal Layer.
+- Shared-Modelle fuer Confidence Levels, Surrogat-Korrelation, Quality Signals und federative Sichtbarkeitsklassen.
+- Tests fuer die neuen Shared-Modelle und ihre Routing-/Impact-Logik.
 
 ### Changed
 
 - GitHub-Actions-Workflows auf Node-24-faehige Major-Versionen von `actions/checkout` und `actions/setup-python` angehoben.
+- Root-README um Observability-, Federation- und Strangler-Prinzipien aus der Watchdog-Serie erweitert.
 
 ## [0.1.0-alpha.1] - 2026-03-29
 

README.md

@@ -21,40 +21,103 @@ Dieses Repository ist der Beweis, dass die Technologie reif ist — und dass der
 | [`sanctions/`](sanctions) | 🟢 Live | Sanctions & PEP Screening auf Basis von OpenSanctions + yente — deployed auf [sanction.endvater.de](https://sanction.endvater.de) | Dow Jones R&C, World-Check, Sanction Scanner |
 | [`horizon/`](horizon) | ⚪ Geplant | Regulatory Horizon Scanner — EUR-Lex, BaFin, EBA/ESMA automatisch gescrapt und LLM-klassifiziert | VÖB RADAR, CUBE, msg LCM |
 | [`osint/`](osint) | ⚪ Geplant | Adverse Media & OSINT — RSS-Aggregation, LLM-Klassifikation, Entity Resolution | LexisNexis, Quantexa, Chainalysis |
-| [`shared/`](shared) | 🟡 Basis | Gemeinsame Infrastruktur: Neo4j-Connector, LLM-Gateway, Confidence Framework, Config | — |
+| [`observability/`](observability) | 🟡 Blueprint | Qualitaets-Layer fuer Detection Integrity, Data Trust, Service Health und Business Impact | isolierte Monitoring-Kacheln, fachlich blinde DQ-Programme |
+| [`federation/`](federation) | 🟡 Blueprint | Foederatives Schichtenmodell: oeffentlicher, foederativer und bankinterner Layer | Single-Bank-Silos, Vendor-Blackboxes |
+| [`shared/`](shared) | 🟡 Basis | Gemeinsame Infrastruktur: Neo4j-Connector, LLM-Gateway, Confidence, Observability- und Federation-Modelle | — |
 
 ## Architektur
 
 ```
-┌─────────────────────────────────────────────────────────────────────┐
-│                            Beyond AI                                │
-│                                                                     │
-│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────────────┐    │
-│  │  sanctions/  │  │  horizon/   │  │         osint/           │    │
-│  │  Screening   │  │  Scanner    │  │  Adverse Media           │    │
-│  │  PEP/Lists   │  │  Norms      │  │  Entity Resolution       │    │
-│  └──────┬───────┘  └──────┬──────┘  └───────────┬──────────────┘    │
-│         │                 │                      │                   │
-│  ┌──────┴─────────────────┴──────────────────────┴────────────────┐  │
-│  │                          shared/                               │  │
-│  │  Neo4j · LiteLLM Gateway (Ollama/Claude) · Confidence         │  │
-│  │  Config · FastAPI Boilerplate · Prefect Scheduler             │  │
-│  └───────────────────────────┬────────────────────────────────────┘  │
-│                              │                                       │
-│  ┌───────────────────────────┴────────────────────────────────────┐  │
-│  │               Datenquellen & Matching-Layer                    │  │
-│  │  OpenSanctions · yente · nomenklatura · FollowTheMoney (FtM)  │  │
-│  │  ICIJ Offshore Leaks · EUR-Lex · BaFin · EBA · OFAC · UN     │  │
-│  │  Splink (Entity Resolution) · Aleph (OCCRP) · watchman        │  │
-│  └────────────────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────────────┘
-         │
-         ▼
-  FinRegAgents (upstream)
-  github.com/endvater/finreg-agents
-  Confidence-aware Validation Framework
+┌───────────────────────────────────────────────────────────────────────┐
+│                              Beyond AI                               │
+│                                                                       │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐           │
+│  │ sanctions/  │  │ horizon/    │  │       osint/        │           │
+│  │ Screening   │  │ Scanner     │  │ Adverse Media       │           │
+│  │ PEP/Lists   │  │ Norms       │  │ Entity Resolution   │           │
+│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘           │
+│         │                │                    │                      │
+│  ┌──────┴────────────────┴────────────────────┴────────────────────┐ │
+│  │ observability/                                                  │ │
+│  │ Detection Integrity · Data Trust · Service Health · Impact Map  │ │
+│  └──────┬───────────────────────────────────────────────────────────┘ │
+│         │                                                           │
+│  ┌──────┴───────────────────────────────────────────────────────────┐ │
+│  │ federation/                                                     │ │
+│  │ Public Layer · Federated Layer · Internal Layer                 │ │
+│  │ Confidence-aware Sidecars · Privacy-preserving Signals          │ │
+│  └──────┬───────────────────────────────────────────────────────────┘ │
+│         │                                                           │
+│  ┌──────┴───────────────────────────────────────────────────────────┐ │
+│  │ shared/                                                         │ │
+│  │ Neo4j · LLM Gateway · Confidence · Observability Models         │ │
+│  │ Federation Models · Config · FastAPI Boilerplate                │ │
+│  └──────┬───────────────────────────────────────────────────────────┘ │
+│         │                                                           │
+│  ┌──────┴───────────────────────────────────────────────────────────┐ │
+│  │ Datenquellen und Signale                                        │ │
+│  │ Public Data · Federated Signals · Internal Telemetry            │ │
+│  │ OpenSanctions · EUR-Lex · BaFin · EBA · ICIJ · OpenCorporates   │ │
+│  └──────────────────────────────────────────────────────────────────┘ │
+└───────────────────────────────────────────────────────────────────────┘
+          │
+          ▼
+   FinRegAgents (upstream)
+   github.com/endvater/finreg-agents
+   Confidence-aware Validation Framework
 ```
 
+## Neue Architekturprinzipien
+
+### 1. Observability als Qualitaets-Layer
+
+Beyond AI erweitert die klassische Produktarchitektur um einen expliziten
+Qualitaets-Layer ueber alle FinCrime-Module hinweg:
+
+- `Business-Qualitaet`: erkennt das System noch das Richtige?
+- `Daten-Qualitaet`: kann das Institut der Entscheidungsbasis trauen?
+- `IT-Service-Qualitaet`: laeuft die Erkennungskette noch technisch integer?
+
+Die entscheidende Regel lautet: Nicht jedes Data- oder IT-Signal gehoert ins
+Compliance-Cockpit. Sichtbar werden nur Signale mit nachweisbarer
+`Business Impact`-Wirkung auf Regeln, Modelle, Populationen, Faelle oder
+Kontrollhandlungen.
+
+### 2. Foederatives Schichtenmodell
+
+Die Beyond-AI-Architektur folgt einem dreistufigen Sichtbarkeitsmodell:
+
+- `Public Layer`: alles, was aus Regulatorik, oeffentlichen Typologien und
+  offenen Datenquellen ohnehin sichtbar ist
+- `Federated Layer`: institutionsuebergreifende Signale, Regeln und Muster ohne
+  pauschalen Rohdatenaustausch
+- `Internal Layer`: bankspezifische Modelle, Graphen, Entscheidungs- und
+  Priorisierungslogik
+
+Technologie ist kopierbar. Netzwerke, Governance und geteilte
+Qualitaetssicherung sind es nicht.
+
+### 3. Legacy-Modernisierung nach dem Strangler-Prinzip
+
+Beyond AI geht davon aus, dass reale AML-Landschaften nicht cloud-nativ
+beginnen. Deshalb ist `Mirror First` Teil der Architektur:
+
+- Event Mirrors und Shadow Pipelines vor produktiver Kernablaesung
+- Surrogat-IDs mit `Confidence Levels`, wenn keine echte End-to-End-Trace-ID
+  existiert
+- Strangeln von Faehigkeiten statt romantischer Komplett-Ablage von Systemen
+- Vendor-Lock-in bedeutet oft: zuerst Umgebung stranglen, nicht den Kern
+
+## Architekturtexte
+
+Die Repo-Architektur wird nicht nur im Code, sondern auch in den Watchdog-
+Texten entfaltet:
+
+- [Beyond AI/FinCrime OS — Weil Technologie kopierbar ist. Netzwerke nicht.](https://watchdog.endvater.de/2026/03/beyond-ai-weil-technologie-kopierbar-ist-netzwerke-nicht/)
+- [Beyond AI/FinCrime OS: Die drei Schichten der Unsichtbarkeit](https://watchdog.endvater.de/2026/03/beyond-ai-fincrime-os-die-drei-schichten-der-unsichtbarkeit/)
+- Observability-Serie Teil II: Business-, Daten- und IT-Service-Qualitaet als gemeinsamer Qualitaets-Layer
+- Observability-Serie Teil III: Strangler-Fig-Modernisierung fuer die Legacy-Bank
+
 ## Quickstart
 
 ```bash
@@ -198,6 +261,11 @@ DSGV, BVR oder ein vergleichbarer Verband institutionalisiert das System. Die Ba
 
 Wir suchen Institute — Sparkassen, Volksbanken, Landesbanken — die den genossenschaftlichen Gedanken in Code übersetzen wollen.
 
+Das technische Modell dazu ist jetzt explizit in [`federation/`](federation)
+dokumentiert: nicht nur als Betriebsform, sondern als mehrschichtige
+Detection-Architektur aus sichtbaren, foederierten und vollstaendig internen
+Erkennungsebenen.
+
 > *Was noch fehlt, ist kein Tool. Es ist der erste Telefonanruf.*
 > — FinCrime OS 2026
 

federation/README.md

@@ -0,0 +1,69 @@
+# Beyond AI — Federation Layer
+
+**Status: 🟡 Blueprint / Architekturmodul**
+
+`federation/` ist die explizite Repo-Verankerung der These:
+
+**Technologie ist kopierbar. Netzwerke nicht.**
+
+Beyond AI versteht Foederation deshalb nicht nur als Betriebsform, sondern als
+Detection-Architektur mit unterschiedlichen Sichtbarkeits- und
+Kooperationsschichten.
+
+## Das Drei-Schichten-Modell
+
+| Layer | Sichtbarkeit fuer Externe | Typische Inhalte | Sharing-Modus |
+|------|----------------------------|------------------|---------------|
+| `public` | hoch | oeffentliche Typologien, Sanktionslisten, regulatorische Schwellen, Standard-KYC | public source |
+| `federated` | niedrig | anonymisierte Muster, gemeinsame Heuristiken, privacy-preserving Signale, Cross-Bank-Learning | anonymized / privacy-preserving |
+| `internal` | null | bankspezifische Modelle, Priorisierung, interne Graph-Analytik, proprietaere Entscheidungslogik | institution only |
+
+## Warum das relevant ist
+
+Ein professioneller Geldwaescher kennt heute viele Elemente des oeffentlichen
+Layers: Typologien, Schwellenwerte, Standardkontrollen, offene Watchlists.
+Er kann gegen diese sichtbare Logik optimieren.
+
+Ein Beyond-AI-System soll deshalb nicht nur "besser erkennen", sondern auch
+die Sichtbarkeit seiner eigentlichen Erkennungstiefe steuern:
+
+- `public`: regulatorisch nachvollziehbar und erwartbar
+- `federated`: zwischen Instituten lernfaehig, aber fuer Angreifer opak
+- `internal`: vollstaendig bankspezifisch und nicht testbar von aussen
+
+## Foederation heisst nicht Rohdatenaustausch
+
+Das Repo geht bewusst nicht von pauschalem Teilen sensibler Rohdaten aus.
+Foederation meint hier in erster Linie:
+
+- geteilte Regeln und Kuratierung
+- anonymisierte oder aggregierte Muster
+- privacy-preserving Signale
+- gemeinsame Qualitaetssicherung
+- gemeinsames Betriebs- und Governance-Modell
+
+## Beziehung zur Legacy-Modernisierung
+
+In realen Banken laesst sich nicht jede Vendor-Blackbox direkt stranglen.
+Foederation hilft auch dort:
+
+- gemeinsame Kuratierung rund um Blackboxes
+- gemeinsame Referenzdaten- und Trust-Layer
+- geteilte Priorisierungs- und Kontextlogik
+- Verlagerung von Wissen aus Vendor-Silos in einen gemeinsamen Layer
+
+## Kernartefakte
+
+- `VisibilityLayer`
+- `SharingMode`
+- `DetectionLayer`
+- `FederatedCapability`
+
+Diese Modelle liegen in `shared/federation/`.
+
+## Roadmap
+
+- [ ] Default Detection Layers fuer Beyond AI festziehen
+- [ ] Sharing-Regeln fuer Signale aus `sanctions/` definieren
+- [ ] Public/Federated/Internal-Klassifikation fuer künftige Module einfuehren
+- [ ] Governance-Playbook fuer foederativen Betrieb dokumentieren

federation/__init__.py

@@ -0,0 +1 @@
+"""Beyond AI federation module placeholder."""

observability/README.md

@@ -0,0 +1,78 @@
+# Beyond AI — Observability Layer
+
+**Status: 🟡 Blueprint / Architekturmodul**
+
+Der `observability/`-Layer erweitert Beyond AI um eine explizite
+Qualitaetsschicht fuer FinCrime-Systeme. Nicht mehr nur: "Funktioniert das
+Modul?" Sondern: "Erkennt das Institut noch verlaesslich, worauf diese Sicht
+beruht - und wo sie gerade bruechig wird?"
+
+## Die drei Qualitaetsdimensionen
+
+Beyond AI behandelt Observability nicht als reines IT-Monitoring, sondern als
+Layer ueber drei Ebenen:
+
+- `Business-Qualitaet`
+  Erkennen Regeln, Modelle und Workflows noch die richtigen Risiken?
+- `Daten-Qualitaet`
+  Kann das Institut der Entscheidungsbasis trauen?
+- `IT-Service-Qualitaet`
+  Laeuft die Erkennungskette technisch noch integer?
+
+## Designregeln
+
+1. Nicht jedes Datenproblem ist ein Compliance-Problem.
+2. Nicht jede technische Degradation gehoert ins Compliance-Cockpit.
+3. Sichtbar werden nur Signale mit `Business Impact`.
+4. Korrelationen ohne native Trace-ID brauchen `Surrogat-IDs` mit
+   `Confidence Levels`.
+5. Die Navigationslogik ist wichtiger als die Kachelzahl:
+   `fachliches Symptom -> Datenursache -> IT-Ursache -> Massnahme`.
+
+## Architektur
+
+```
+                   Beyond AI Product Modules
+      sanctions/        horizon/          osint/
+           │                │                │
+           └────────────────┼────────────────┘
+                            │
+                    observability/
+                            │
+      ┌─────────────────────┼─────────────────────┐
+      │                     │                     │
+Detection Integrity     Data Trust         Service Health
+      │                     │                     │
+      └─────────────────────┼─────────────────────┘
+                            │
+                    Business Impact Map
+                            │
+                    Compliance Cockpit
+```
+
+## Kernartefakte
+
+- `QualitySignal`
+- `CorrelationHandle`
+- `IncidentSeverity`
+- `SurfaceTarget`
+
+Diese Modelle liegen in `shared/observability/` und sind bewusst
+moduluebergreifend formuliert: Der Sanctions Screener, der Horizon Scanner und
+spaetere Graph- oder Workflow-Komponenten sollen dieselbe Sprache fuer
+Qualitaet und Impact sprechen.
+
+## Was dieser Layer bewusst nicht ist
+
+- kein allgemeines NOC-Dashboard
+- kein ungefilterter Data-Quality-Alarmstrom
+- kein Ersatz fuer Modellvalidierung oder interne Revision
+- kein Versuch, jede lokale technische Stoerung in die Compliance zu werfen
+
+## Roadmap
+
+- [ ] Impact-aware Signals aus `sanctions/` einspeisen
+- [ ] Read-only Detection Integrity fuer Vendor-TM-Exports vorbereiten
+- [ ] Data-Trust-Indikatoren fuer Referenzdatenfeeds definieren
+- [ ] Service-Health-Signale mit Business Impact verknuepfen
+- [ ] Compliance-Cockpit-Projektion als eigene API/Oberflaeche ableiten

observability/__init__.py

@@ -0,0 +1 @@
+"""Beyond AI observability module placeholder."""

pyproject.toml

@@ -11,4 +11,4 @@ ignore = [
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
-testpaths = ["sanctions/tests"]
+testpaths = ["sanctions/tests", "tests"]

shared/confidence/__init__.py

@@ -0,0 +1,35 @@
+"""Shared confidence primitives for Beyond AI."""
+
+from enum import StrEnum
+
+
+class ConfidenceLevel(StrEnum):
+    """Small shared confidence scale for model, retrieval and correlation signals."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+    @property
+    def rank(self) -> int:
+        return {
+            ConfidenceLevel.LOW: 0,
+            ConfidenceLevel.MEDIUM: 1,
+            ConfidenceLevel.HIGH: 2,
+        }[self]
+
+    def at_least(self, minimum: "ConfidenceLevel") -> bool:
+        return self.rank >= minimum.rank
+
+    @classmethod
+    def from_score(cls, score: float) -> "ConfidenceLevel":
+        if not 0.0 <= score <= 1.0:
+            raise ValueError("score must be between 0.0 and 1.0")
+        if score >= 0.85:
+            return cls.HIGH
+        if score >= 0.60:
+            return cls.MEDIUM
+        return cls.LOW
+
+
+__all__ = ["ConfidenceLevel"]

shared/federation/__init__.py

@@ -0,0 +1,17 @@
+"""Shared federation models for Beyond AI."""
+
+from .models import (
+    DetectionLayer,
+    FederatedCapability,
+    SharingMode,
+    VisibilityLayer,
+    default_detection_layers,
+)
+
+__all__ = [
+    "DetectionLayer",
+    "FederatedCapability",
+    "SharingMode",
+    "VisibilityLayer",
+    "default_detection_layers",
+]