Expand AML observability PoC structure

[endvater]

Summary

• restructure the observability PoC into clearer modules for models, trace helpers, detection, case management, privacy, pipeline, and queries
• add synthetic JSONL fixtures, runnable demo scripts, and a walkthrough notebook so the PoC is easier to execute and reference
• split the observability tests into focused files and refresh the root plus observability READMEs to match the new layout

Testing

• pytest -q
• ruff check observability shared tests
• python3 -m observability.scripts.run_demo --limit 3

[endvater]

Code Review: AML Observability PoC — Erweiterung

Starker PR. Das Refactoring löst die strukturellen Schwächen aus PR #14 und alle Review-Punkte von damals wurden adressiert. Die Schichtentrennung ist jetzt deutlich klarer, die Detection-Logik ist in ein eigenes Objekt gewandert und die Privacy/Retention-Schicht ist eine sinnvolle Ergänzung.

---

✅ Positives

• DetectionDecision als eigenständiges Objekt — alert_created ist jetzt sauber als Property an combined_score >= alert_threshold gebunden, kein loser Entscheidungscode mehr in der Pipeline.
• combined_score = max(model_score, rule_override_score) — semantisch sauberer als der gewichtete Blend aus PR #14: die Regel setzt einen Mindest-Score (Floor), keine additive Verzerrung.
• _require_event Helper in queries.py — der next()-Bug aus PR #14 ist korrekt und konsistent gelöst; eine gemeinsame Hilfsfunktion für alle drei Query-Typen.
• privacy.py — datenschutzrechtlich sinnvolle Ergänzung; Non-Alert-Traces werden minimiert, Alert-Traces vollständig behalten. Das ist ein klares, nachvollziehbares Retention-Prinzip.
• auto_case_feedback-Parameter — nützlich für Demos ohne manuelle Disposition-Objekte.
• UAE aus ILLUSTRATIVE_HIGH_RISK_JURISDICTIONS entfernt — gut.
• test_explain_why_flagged_raises_clear_error_for_incomplete_trace — direkte Regression-Abdeckung des Bugs aus dem letzten Review.

---

⚠️ selective_trace_retention — Test prüft keine echte Filterung

tests/test_observability_trace.py:47-60

Der Eingabe-Trace hat genau 3 Events (FEATURES_DERIVED, MODEL_SCORED, NO_ALERT), die alle im Retained-Set liegen. Der Test beweist nicht, dass Events außerhalb des Sets (RECEIVED, INGESTED, RULE_EVALUATED) wirklich herausgefiltert werden. Ein Trace mit 5–6 Events und Assertion auf len == 3 wäre aussagekräftiger.

---

⚠️ Implementierungskonstanten im Public API

observability/__init__.py:7-9

DEFAULT_EVALUATED_RULES und ILLUSTRATIVE_HIGH_RISK_JURISDICTIONS sind in __all__ exportiert. Das sind interne PoC-Konstanten, keine stabilen API-Versprechen. Wenn externe Nutzer darauf aufbauen, erschwert das spätere Anpassungen. Empfehlung: aus __all__ entfernen oder mit einem _-Präfix als intern kennzeichnen.

---

⚠️ Demo-Skript hängt von nicht-eingecheckten Fixtures ab

observability/scripts/run_demo.py:43

Der Default-Pfad observability/data/synthetic_transactions.jsonl existiert nicht im Repository. run_demo.py ohne vorheriges Ausführen von generate_synthetic_data.py gibt einen unklaren FileNotFoundError. Eine klare Fehlermeldung oder ein Hinweis im README wäre hilfreich.

---

💡 Minimierter Trace gibt keinen Hinweis auf Retention-Modus

observability/privacy.py:54-60

Das von selective_trace_retention zurückgegebene AMLTrace-Objekt ist äußerlich identisch mit einem vollständigen Trace. Wer das Ergebnis weiterverarbeitet, kann nicht erkennen, dass Events fehlen. Zumindest die RetentionDecision sollte gemeinsam zurückgegeben oder geloggt werden.

---

💡 walkthrough.ipynb ist ein leerer Platzhalter

74 Zeilen ohne inhaltliche Zellen. Entweder mit einem minimalen Walkthrough füllen oder vorerst weglassen, um keine falschen Erwartungen zu wecken.

---

Zusammenfassung

Kategorie	Bewertung
Architektur & Refactoring	✅ Deutliche Verbesserung gegenüber PR #14
PR #14-Review-Punkte adressiert	✅ Alle
Testabdeckung (11 Tests, 3 Dateien)	✅ Gut
Retention-Test-Tiefe	⚠️ Schwache Filterprüfung
Public-API-Scope der Konstanten	⚠️ Unnötig breit
Demo-Skript-Robustheit	⚠️ Fehlende Fixtures
Minimierungs-Transparenz	💡 Verbesserungswürdig
Notebook-Inhalt	💡 Platzhalter

Der PR ist in gutem Zustand. Die ⚠️-Punkte sind lösbar — am wichtigsten: der Retention-Test und die Konstanten im Public API.

---

Generated by Claude Code

[endvater]

Addressed the review points in 30aa20a:

• strengthened the retention test so the input trace now includes received, ingested, and rule_evaluated events, and the assertion verifies that summary retention really filters them out
• removed PoC constants from the top-level observability package API so DEFAULT_EVALUATED_RULES and ILLUSTRATIVE_HIGH_RISK_JURISDICTIONS are no longer exported from observability.init
• made the demo loader fail with a clearer FileNotFoundError that points to python3 -m observability.scripts.generate_synthetic_data when explicit paths are missing
• added apply_trace_retention() so callers can keep the RetentionDecision together with the retained trace instead of losing the minimization context
• expanded the walkthrough notebook into an actual mini-walkthrough using the checked-in fixture data

One clarification: the synthetic JSONL fixtures are already checked into observability/data/, so the default demo path is available in the repository; the new error path mainly improves the experience when someone passes a missing custom path.

Verification is still clean:

• pytest -q
• ruff check observability shared tests
• python3 -m observability.scripts.run_demo --limit 3

[endvater]

Follow-up Review: Commit 30aa20a — "Tighten observability demo and retention flow"

Alle vier ⚠️-Punkte aus dem letzten Review wurden adressiert. 12/12 Tests grün.

---

✅ Was gefixt wurde

Review-Punkt	Umsetzung
Retention-Test zu schwach	Trace jetzt mit 6 Events (RECEIVED, INGESTED, RULE_EVALUATED + 3 retained); explizite Assertion, dass gefilterte Typen nicht im Ergebnis sind
Konstanten im Public API	ALERT_THRESHOLD, DEFAULT_EVALUATED_RULES, ILLUSTRATIVE_HIGH_RISK_JURISDICTIONS aus __init__.py und __all__ entfernt
Demo-Skript ohne Fehlermeldung	read_jsonl wirft jetzt FileNotFoundError mit Hinweis auf generate_synthetic_data
Minimierung unsichtbar	Neue apply_trace_retention-Funktion gibt (RetentionDecision, AMLTrace) zurück; Demo zeigt Event-Count-Delta wenn minimiert
Notebook leer	Notebook hat jetzt 5 inhaltliche Zellen mit vollständigem Walkthrough

---

⚠️ Eine neue Inkonsistenz: README sagt "eingecheckte Fixtures", aber observability/data/ fehlt im Repo

observability/README.md und scripts/run_demo.py

Der Commit enthält diesen README-Text:

"Die Demo nutzt standardmäßig die eingecheckten Dateien in observability/data/."

Und auch das Notebook geht davon aus, dass die Fixtures vorhanden sind. Aber observability/data/ ist nicht im Repository — git ls-tree findet keine JSONL-Dateien. Der verbesserte FileNotFoundError federt das ab, ist aber ein Widerspruch zur Dokumentation.

Entweder die generierten Fixtures eincheckken (generate_synthetic_data.py einmal ausführen und die JSONL-Dateien committen), oder die README auf die Zwei-Schritt-Anleitung zurücksetzen.

---

💡 Minor: test_read_jsonl_raises_helpful_error_for_missing_fixture nutzt try/except statt pytest.raises

# aktuell
try:
    read_jsonl(missing_path)
except FileNotFoundError as exc:
    message = str(exc)
else:
    raise AssertionError(...)

Idiomatischer wäre:

with pytest.raises(FileNotFoundError, match="generate_synthetic_data"):
    read_jsonl(missing_path)

Kein Bug, aber konsistenter mit dem Rest der Testsuite (die pytest.raises bereits verwendet).

---

Fazit: Der Kern des Review ist erledigt. Einziger echter Nachfolger: die fehlenden Fixture-Dateien im Repository, damit README und Notebook nicht ins Leere zeigen.

---

Generated by Claude Code

[endvater]

Added a paper-facing extension in 1472bcc:

• introduced observability/TECHNICAL_SPEC.md as a formal description of the current AMLTrace / AMLTraceEvent model, layer mapping, decision semantics, and retention behavior
• extended the notebook with a concrete missing-data / false-negative walkthrough, using the existing event-centric model instead of introducing a second competing trace abstraction
• made beneficiary_jurisdiction nullable in the PoC input model so the walkthrough can demonstrate how upstream data loss becomes visible in transformed features and downstream detection outcomes
• added a regression test for the missing-jurisdiction scenario to keep that observability story executable

Verification remains clean:

• pytest -q
• ruff check observability shared tests
• python3 -m observability.scripts.run_demo --limit 3

[endvater]

Addressed in 734f3f1. The README mismatch came from .gitignore: the JSONL fixtures existed locally but were not tracked. I updated .gitignore to allow observability/data/*.jsonl and added both files to the PR, so observability/data/synthetic_transactions.jsonl and observability/data/synthetic_cases.jsonl are now part of #15.

[endvater]

Follow-up Review: Commit 734f3f1 — "Track observability fixture data"

Was neu hinzukommt

Genau das, was der letzte Review-Kommentar als offenen Punkt genannt hatte:

• observability/data/synthetic_transactions.jsonl — 4 synthetische Transaktionen (IRN, DEU, RUS, FRA), konsistent mit generate_synthetic_data.py
• observability/data/synthetic_cases.jsonl — 2 Case-Dispositions (tx-001, tx-003)
• .gitignore — !observability/data/ und !observability/data/*.jsonl als Ausnahmen von der data/-Exclude-Regel

README und Notebook sind jetzt korrekt: die "eingecheckten Fixtures" existieren tatsächlich. ✅

---

❌ Die 2 Failures aus test_aml_observability_poc.py sind weiterhin offen

Dieser Commit adressiert sie nicht — 21/23 Tests grün, 2 Failures bleiben:

FAILED tests/test_aml_observability_poc.py::test_flagged_transaction_generates_alert_and_case_feedback
FAILED tests/test_aml_observability_poc.py::test_change_explanation_detects_feature_and_alert_shift

UAE ist nicht in ILLUSTRATIVE_HIGH_RISK_JURISDICTIONS → kein Alert → beide Assertions schlagen fehl.

Fix: "UAE" → "IRN" in tests/test_aml_observability_poc.py (zwei Stellen).

---

Generated by Claude Code

[endvater]

I checked the current PR head against both the branch and origin/main: this specific UAE-to-IRN issue is already resolved in the code under review. The old file tests/test_aml_observability_poc.py is no longer part of the PR head, and the current test coverage in tests/test_observability_pipeline.py plus tests/test_observability_queries.py already uses IRN. There are also no remaining UAE references in the tracked test or observability code, and the current CI checks on #15 are green. So this looks like a stale review observation rather than an open merge blocker on the latest commit.

[ruthdelalucha]

Strukturelle Verbesserung des Observability-PoC. Die Aufteilung in Detection/CaseMgmt/Privacy-Module ist sauber, die Demo-Skripte und JSONL-Fixtures machen den PoC ausführbar statt nur theoretisch. Tests sind passend aufgeteilt, READMEs aktualisiert. Walkthrough-Notebook ist ein schönes Extra für Reviewer. Passt zum v1.1 Paper-Release. LGTM 🐸