Files
fewo-stommer/app/Communication/Extraction/RiskAssessment.php
T
LarsandClaude Opus 5.5 4170e3bd29 v0.11 U6: risikobasierte KI-Extraktion von Gast- und Portalnachrichten
- Kleines Modell (claude-haiku-5-5) extrahiert Fakten mit Belegstelle und
  Konfidenz; programmatische Prüfung (Gültigkeit, Belegstelle im Original,
  Widerspruch zum gespeicherten Wert oder in der Nachricht, Plausibilität,
  Kritikalität nach Feld und Phase). Widerspruch oder fehlgeschlagene
  Prüfung → Prüfmodell (claude-opus-5-5, serverseitiger Fallback bei
  Ablehnung) unabhängig von der Konfidenz; solche Fakten nie automatisch.
- Nur geprüfte, bisher fehlende Angaben gehen an den Fakteneingang (Quelle
  „llm“); Zeitraum/Personen nur als Änderungswunsch (M06); Rest als
  Vorschlag im Posteingang („Vorschläge übernehmen“).
- Versionierte Prompts mit Platzhaltern, JSON-Schema mit eigener
  Validierung und einer Wiederholung; Ausfall/Ablehnung → sicherer
  Rückfall zur Vermieterin. HTTP-Client, kein SDK (laut Plan).
- Dienst „KI: Gästekommunikation“ verdrahtet, standardmäßig aus;
  Schlüssel je Mandant oder FEWO_AI_API_KEY; Verbrauch in service_usages.
- messages:extract alle fünf Minuten; ai:evaluate misst Fehlwerte und
  übersehene Angaben getrennt (M05).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 13:49:51 +01:00

156 lines
6.5 KiB
PHP
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<?php
namespace App\Communication\Extraction;
use App\Actions\ContributeCaseFacts;
use App\Models\Booking;
use App\Process\CaseRequirements;
use Carbon\CarbonImmutable;
/**
* The programmatic risk check of an extraction (v0.11, CH-14). The model's confidence is no calibrated probability:
* it may trigger a review, never waive one. Criticality comes from the field, the phase and the kind of deviation;
* contradictions and failed plausibility checks call for the review model regardless of the confidence, and are never
* taken over automatically. Thresholds are configured and calibrated with test messages (go-live condition).
*/
class RiskAssessment
{
/** Details whose automatic completion is harmless in every phase. */
private const ADMINISTRATIVE = ['guest.phone', 'booking.arrival_time'];
/**
* Checks every fact and marks why it may not be taken over automatically.
*
* @param array{facts: list<array{field: string, value: string, evidence: string, confidence: float|int}>, change_requests: list<array{field: string, value: string, evidence: string}>, intent: string, uncertainties: list<string>} $extraction
* @return list<array{field: string, value: string, evidence: string, confidence: float, criticality: float, problems: list<string>}>
*/
public function facts(Booking $booking, string $message, array $extraction): array
{
$checked = [];
$values = [];
foreach ($extraction['facts'] as $fact) {
$values[$fact['field']][] = mb_strtolower(trim($fact['value']));
}
foreach ($extraction['facts'] as $fact) {
$field = $fact['field'];
$value = trim($fact['value']);
$problems = [];
if (! CaseRequirements::isValid($field, $value)) {
$problems[] = 'Wert ungültig';
}
if (! $this->evidenceFound($message, $fact['evidence'])) {
$problems[] = 'Belegstelle nicht in der Nachricht';
}
if (count(array_unique($values[$field] ?? [])) > 1) {
$problems[] = 'widersprüchliche Angaben in derselben Nachricht';
}
$current = CaseRequirements::value($booking, $field);
if (CaseRequirements::isValid($field, $current) && mb_strtolower(trim((string) $current)) !== mb_strtolower($value)) {
$problems[] = 'weicht vom gespeicherten Wert ab';
}
$problems = [...$problems, ...$this->plausibility($booking, $field, $value)];
$checked[] = [
'field' => $field,
'value' => $value,
'evidence' => $fact['evidence'],
'confidence' => max(0.0, min(1.0, (float) $fact['confidence'])),
'criticality' => $this->criticality($booking, $field),
'problems' => $problems,
];
}
return $checked;
}
/**
* Whether the review model has to look at the extraction: any contradiction or failed check, any wish to change
* something in a binding phase, an uncertainty the model reported, or criticality × (1 − confidence) above the
* configured threshold.
*
* @param list<array{criticality: float, confidence: float, problems: list<string>}> $facts
* @param array{change_requests: list<mixed>, uncertainties: list<string>} $extraction
*/
public function needsReview(Booking $booking, array $facts, array $extraction): bool
{
if ($extraction['uncertainties'] !== [] || ($extraction['change_requests'] !== [] && $booking->offer_version > 0)) {
return true;
}
$threshold = (float) config('fewo.ai.escalate_above', 0.2);
foreach ($facts as $fact) {
if ($fact['problems'] !== [] || $threshold < $fact['criticality'] * (1 - $fact['confidence'])) {
return true;
}
}
return false;
}
/**
* Whether a checked fact may go to the fact intake automatically: no problem, confident enough, the detail not
* known yet, and no stay detail (those are change requests). The intake applies its own rules on top.
*
* @param array{field: string, confidence: float, problems: list<string>} $fact
*/
public function mayTakeOver(Booking $booking, array $fact): bool
{
return $fact['problems'] === []
&& $fact['confidence'] >= (float) config('fewo.ai.min_confidence', 0.85)
&& ! in_array($fact['field'], ContributeCaseFacts::STAY_FIELDS, true)
&& ! CaseRequirements::isValid($fact['field'], CaseRequirements::value($booking, $fact['field']))
&& (in_array($fact['field'], self::ADMINISTRATIVE, true) || str_starts_with($fact['field'], 'guest.'));
}
public function evidenceFound(string $message, string $evidence): bool
{
$normalise = fn (string $text): string => mb_strtolower(trim((string) preg_replace('/\s+/u', ' ', $text)));
$evidence = $normalise($evidence);
return $evidence !== '' && str_contains($normalise($message), $evidence);
}
private function criticality(Booking $booking, string $field): float
{
return match (true) {
in_array($field, self::ADMINISTRATIVE, true) => 0.3,
in_array($field, ContributeCaseFacts::STAY_FIELDS, true), $field === 'guest.email' => 1.0,
ContributeCaseFacts::isBinding($booking) => 0.8,
default => 0.6,
};
}
/**
* @return list<string>
*/
private function plausibility(Booking $booking, string $field, string $value): array
{
return match ($field) {
'booking.guests' => (int) $value > (int) $booking->property?->max_guests ? ['mehr Personen als die Wohnung fasst'] : [],
'booking.arrival', 'booking.departure' => $this->dateProblems($booking, $field, $value),
default => [],
};
}
/**
* @return list<string>
*/
private function dateProblems(Booking $booking, string $field, string $value): array
{
$date = rescue(fn () => CarbonImmutable::parse($value), null, false);
if ($date === null) {
return ['Datum nicht lesbar'];
}
if ($date->isBefore(CarbonImmutable::today())) {
return ['Datum liegt in der Vergangenheit'];
}
if ($field === 'booking.departure' && $booking->arrival !== null && ! $date->isAfter($booking->arrival)) {
return ['Abreise nicht nach der Anreise'];
}
return [];
}
}