docs/SCENE_BLOCK_CONTRACT.md

scene-Block — Kontrakt für Produkt & Monorepo-Team

Für wen: Product Owner + das Team am Monorepo (alami-platform). Was: Die Vision-API bekommt ein neues, optionales Antwortfeld scene mit einer Einschätzung „Ist auf diesem Foto überhaupt Müll?". Status: Kontrakt festgezurrt (Typen im Code), noch nicht aktiv — heute liefert keine Antwort das Feld. Erst nach eurem Go. Gegenstück: alami-platform/docs/VISION-API-BOUNDARY.md.

---

1. Das Problem, das es löst (in einem Satz)

Unser Detektor feuert auf 39 % zufälliger Nicht-Müll-Bilder einen False Positive — jedes davon ist potenziell eine Auszahlung für ein Foto ohne Müll. Der scene-Block liefert ein zweites, unabhängiges Signal: ein Weltmodell schaut sich die Szene an („Katze", „Rasen", „Plastikflasche") und sagt, wie plausibel Müll ist.

2. Was es messbar kann (Stand 2026-07-26)

Gemessen auf 620 Bildern (339 mit Müll, 281 ohne), fair out-of-fold validiert:

Wenn wir …	… dann bleiben von echtem Müll erhalten
80 % der Falsch-Fälle wegfiltern	88 %
90 % der Falsch-Fälle wegfiltern	70 %

Zum Vergleich: die naive Vorversion schaffte bei 80 % Filterwirkung nur 50 %. Details + Methodik: docs/PHASE_A_SCENE_GATE.md §8i.

Ehrliche Grenzen — bitte mitlesen:

• Gemessen auf TACO-Datensatz-Fotos, nicht auf echten App-Uploads. Die Zahl ist eine belastbare Richtgröße, keine Produktionsgarantie.
• Es ist kein 100-%-Detektor. Bei 80 % Filterwirkung gehen 12 % echter Müll-Fotos fälschlich in die Prüfung. Deshalb Punkt 3.

3. Die wichtigste Regel: advisory, nicht Auszahlung

waste_likelihood ist ein Hinweis, kein Urteil.

• ✅ Erlaubt: Einreichung zur manuellen Prüfung markieren, im Admin sortieren/priorisieren, Betrugsmuster sichtbar machen, dem Nutzer einen Hinweis zeigen („Wir konnten keinen Müll erkennen — trotzdem einreichen?").
• ❌ Nicht erlaubt: Trash Coins automatisch verweigern, Einreichung ablehnen, Nutzer sperren — allein aufgrund dieses Werts.

Grund: ein Nutzer, der echten Müll gesammelt hat und wegen eines Modellfehlers leer ausgeht, ist ein schwerer Vertrauensschaden. Der bestehende Review-Pfad (needs_review → Admin gibt frei) fängt das sauber ab.

Falls wir später automatisch verweigern wollen, braucht es eine andere Qualitätsstufe (≥99 % erhaltener Müll) — die ist heute nicht erreicht, und der Weg dahin steht in Punkt 6.

4. Was sich technisch ändert — nichts, bis ihr es nutzt

scene ist ein optionales Feld auf AnalyzeResponse. Es fehlt heute in jeder Antwort. Kein Feld wird umbenannt, entfernt oder in der Bedeutung geändert. Bestehende Clients brauchen keine Zeile Code.

{
  "prediction_id": "…", "model_version": "…", "objects": [ … ], "summary": { … },

  // NEU, optional, fehlt wenn nicht aktiviert:
  "scene": {
    "scene_gate_version": "yolo-worldv2-…",
    "waste_likelihood": 0.87,        // 0..1 — ADVISORY (siehe §3)
    "score_method": "learned",       // "learned" | "max_conf" (Transparenz)
    "waste_objects": [
      { "label": "plastic bottle", "label_de": "Plastikflasche",
        "confidence": 0.81, "bbox_norm": [0.12, 0.4, 0.2, 0.3],
        "material_hint": "plastic" }
    ],
    "non_waste_objects": [
      { "label": "cat", "label_de": "Katze",
        "confidence": 0.88, "bbox_norm": [0.5, 0.1, 0.3, 0.4] }
    ],
    "counts": { "waste": 1, "non_waste": 1 },
    "inventory_text": "Plastikflasche · Katze"   // fertig zum Anzeigen
  }
}

Feldbedeutungen:

Feld	Bedeutung
waste_likelihood	0..1, wie plausibel Müll im Bild ist. Advisory.
score_method	learned = gelerntes Modell, max_conf = einfache Rückfallebene. Immer mitloggen — sonst sind Metriken über verschiedene Stände nicht vergleichbar.
waste_objects / non_waste_objects	erkannte Dinge mit deutschem Label + Box (0..1, wie objects[])
inventory_text	fertiger Anzeigestring, keine eigene Formatierung nötig
counts	Schnellzugriff ohne Listen zu zählen

bbox_norm ist identisch normiert wie in objects[] — dieselbe Overlay-Logik funktioniert.

5. Was wir vom Produkt brauchen (Entscheidungen für den PO)

1. Schwelle: Ab welchem waste_likelihood soll eine Einreichung in die Prüfung wandern? Empfehlung: konservativ starten (nur sehr niedrige Werte markieren), Wirkung beobachten, dann nachziehen. Die Schwelle gehört auf eure Seite — so ändert ihr sie ohne Vision-Deployment.
2. Sichtbarkeit: Sieht der Nutzer etwas (z. B. „kein Müll erkannt") oder zunächst nur der Admin? Empfehlung: erst nur Admin, bis wir Feldzahlen haben.
3. Rollout: Erst mitlaufen lassen und nur loggen (keine Wirkung), damit wir echte Verteilungen sehen — dann entscheiden. Empfehlung: ja.

6. Wie es besser wird (und warum euer Feedback der Motor ist)

Das Modell lernt aus Korrekturen. Über den bereits gebauten Feedback-v2-Pfad (added_items, reasons, action — siehe docs/api.md) kommen genau die Fälle zurück, in denen die KI danebenlag. Damit trainieren wir den Score auf echten App-Fotos statt auf Datensatz-Bildern nach.

Der Weg zum harten Auto-Gate führt nur hierüber. Je mehr Feedback fließt, desto eher ist es realistisch.

7. Offene Punkte auf unserer Seite (Vision)

• Serving: Das Weltmodell läuft heute nur in der Auswertung, nicht im Live-Space (anderer Runtime-Stack, Latenz-Budget zu prüfen). Das ist der nächste Arbeitsblock — Aufwand entsteht bevor ihr etwas tun müsst.
• Latenz: Zusätzliche Inferenz kostet Zeit. Vor Aktivierung messen wir und melden die Zahl; notfalls läuft es asynchron statt im Antwortpfad.

8. Zeitliche Reihenfolge (Vorschlag)

1. Jetzt: Ihr lest den Kontrakt, sagt ob die Feldform passt. (kein Code)
2. Wir bauen Serving + messen Latenz.
3. Schattenbetrieb: Feld wird geliefert, nur geloggt, keine Wirkung.
4. Nach echten Zahlen: PO entscheidet Schwelle + Sichtbarkeit.
5. Später, datenabhängig: Auto-Gate — nur bei ≥99 % erhaltenem Müll.

Vertragsänderungen (Felder, Bedeutungen, Auth) stimmen wir vorher ab — wie Schema-Migrationen, gemäß VISION-API-BOUNDARY.md.