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>
This commit is contained in:
1 parent
dff9e2344e
commit
4170e3bd29
18 files changed
+1130
-7
No files matched your search
@@ -0,0 +1,11 @@
|
||||
<?php
|
||||
|
||||
namespace App\Communication\Extraction;
|
||||
|
||||
use RuntimeException;
|
||||
|
||||
/**
|
||||
* The extraction could not produce a usable result (no key, timeout, refusal, invalid output). The message then
|
||||
* waits for the landlord – the safe fallback of CH-14.
|
||||
*/
|
||||
class ExtractionFailed extends RuntimeException {}
|
||||
@@ -0,0 +1,66 @@
|
||||
<?php
|
||||
|
||||
namespace App\Communication\Extraction;
|
||||
|
||||
use Illuminate\Http\Client\ConnectionException;
|
||||
use Illuminate\Support\Facades\Http;
|
||||
|
||||
/**
|
||||
* The model connection for the extraction (Claude Messages API over HTTP – no SDK dependency, as approved in the
|
||||
* v0.11 plan). One call: system prompt, the message as user content, and a JSON schema the answer must follow
|
||||
* (structured outputs, `output_config.format`). Provider, endpoint and models come from config('fewo.ai').
|
||||
*/
|
||||
class LlmClient
|
||||
{
|
||||
/** Server-side refusal fallback (opt-in default for Claude Opus 5.5). */
|
||||
private const FALLBACK_BETA = 'server-side-fallback-2026-07-01';
|
||||
|
||||
/**
|
||||
* @param array<string, mixed> $schema
|
||||
* @return array{data: array<string, mixed>, model: string, usage: array<string, mixed>}
|
||||
*
|
||||
* @throws ExtractionFailed
|
||||
*/
|
||||
public function structured(string $apiKey, string $model, string $system, string $message, array $schema, string $effort = 'medium'): array
|
||||
{
|
||||
$body = [
|
||||
'model' => $model,
|
||||
'max_tokens' => 4096,
|
||||
'system' => $system,
|
||||
'messages' => [['role' => 'user', 'content' => $message]],
|
||||
'output_config' => ['effort' => $effort, 'format' => ['type' => 'json_schema', 'schema' => $schema]],
|
||||
];
|
||||
$headers = ['x-api-key' => $apiKey, 'anthropic-version' => (string) config('fewo.ai.api_version'), 'content-type' => 'application/json'];
|
||||
if (str_starts_with($model, 'claude-opus-')) {
|
||||
$body['fallbacks'] = 'default';
|
||||
$headers['anthropic-beta'] = self::FALLBACK_BETA;
|
||||
}
|
||||
|
||||
try {
|
||||
$response = Http::withHeaders($headers)->timeout((int) config('fewo.ai.timeout', 40))->retry(2, 2000, throw: false)->post((string) config('fewo.ai.endpoint'), $body);
|
||||
} catch (ConnectionException $exception) {
|
||||
throw new ExtractionFailed('Keine Verbindung zum KI-Dienst: '.$exception->getMessage(), previous: $exception);
|
||||
}
|
||||
|
||||
if (! $response->successful()) {
|
||||
throw new ExtractionFailed('KI-Dienst antwortet mit '.$response->status().'.');
|
||||
}
|
||||
|
||||
$payload = (array) $response->json();
|
||||
$stop = $payload['stop_reason'] ?? null;
|
||||
if ($stop === 'refusal') {
|
||||
throw new ExtractionFailed('Der KI-Dienst hat die Auswertung abgelehnt.');
|
||||
}
|
||||
if ($stop === 'max_tokens') {
|
||||
throw new ExtractionFailed('Die Antwort des KI-Dienstes ist unvollständig.');
|
||||
}
|
||||
|
||||
$text = collect((array) ($payload['content'] ?? []))->where('type', 'text')->pluck('text')->implode('');
|
||||
$data = json_decode($text, true);
|
||||
if (! is_array($data)) {
|
||||
throw new ExtractionFailed('Die Antwort des KI-Dienstes ist kein gültiges JSON.');
|
||||
}
|
||||
|
||||
return ['data' => $data, 'model' => (string) ($payload['model'] ?? $model), 'usage' => (array) ($payload['usage'] ?? [])];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,161 @@
|
||||
<?php
|
||||
|
||||
namespace App\Communication\Extraction;
|
||||
|
||||
use App\Models\Booking;
|
||||
use App\Models\InboundMessage;
|
||||
use App\Process\CaseRequirements;
|
||||
|
||||
/**
|
||||
* The model side of the extraction (v0.11, CH-14): versioned prompts with defined placeholders, a JSON schema for the
|
||||
* answer and its validation here (the answer is checked, not trusted). The small model extracts; the review model
|
||||
* sees the original and the first extraction. Both only return candidates – nothing is stored or changed here.
|
||||
*/
|
||||
class MessageExtractor
|
||||
{
|
||||
public function __construct(private LlmClient $client) {}
|
||||
|
||||
/**
|
||||
* @return array{data: 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>}, model: string}
|
||||
*
|
||||
* @throws ExtractionFailed
|
||||
*/
|
||||
public function extract(string $apiKey, InboundMessage $message, Booking $booking): array
|
||||
{
|
||||
return $this->call($apiKey, (string) config('fewo.ai.small_model'), $this->prompt('', $booking), $this->messageText($message), 'medium');
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<string, mixed> $first
|
||||
* @return array{data: 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>}, model: string}
|
||||
*
|
||||
* @throws ExtractionFailed
|
||||
*/
|
||||
public function review(string $apiKey, InboundMessage $message, Booking $booking, array $first): array
|
||||
{
|
||||
return $this->call($apiKey, (string) config('fewo.ai.review_model'), $this->prompt('-review', $booking, ['first_extraction' => json_encode($first, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT)]), $this->messageText($message), 'high');
|
||||
}
|
||||
|
||||
public static function promptVersion(): string
|
||||
{
|
||||
return (string) config('fewo.ai.prompt_version', 'v1');
|
||||
}
|
||||
|
||||
/**
|
||||
* The prompt of the configured version with every placeholder filled; an unknown placeholder is an error.
|
||||
*
|
||||
* @param array<string, string> $extra
|
||||
*/
|
||||
public function prompt(string $variant, Booking $booking, array $extra = []): string
|
||||
{
|
||||
$path = resource_path('prompts/extraction/'.self::promptVersion().$variant.'.md');
|
||||
if (! is_file($path)) {
|
||||
throw new ExtractionFailed('Prompt '.self::promptVersion().$variant.' fehlt.');
|
||||
}
|
||||
|
||||
$values = [
|
||||
'phase' => match (true) {
|
||||
$booking->isBinding() => 'binding booking (contract exists; changes are only wishes)',
|
||||
$booking->offer_version > 0 => 'binding offer sent, not yet accepted',
|
||||
default => 'non-binding request',
|
||||
},
|
||||
'requested_fields' => implode(', ', $booking->openDataRequest()?->fields ?? CaseRequirements::missing($booking)) ?: 'none',
|
||||
'known_fields' => $this->knownFields($booking),
|
||||
'today' => now()->toDateString(),
|
||||
...$extra,
|
||||
];
|
||||
|
||||
$prompt = preg_replace_callback('/\{\{\s*(\w+)\s*\}\}/', function (array $match) use ($values): string {
|
||||
if (! array_key_exists($match[1], $values)) {
|
||||
throw new ExtractionFailed('Unbekannter Platzhalter {{'.$match[1].'}}.');
|
||||
}
|
||||
|
||||
return $values[$match[1]];
|
||||
}, (string) file_get_contents($path));
|
||||
|
||||
return (string) $prompt;
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
public static function schema(): array
|
||||
{
|
||||
return (array) json_decode((string) file_get_contents(resource_path('prompts/extraction/schema.json')), true);
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array{data: 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>}, model: string}
|
||||
*/
|
||||
private function call(string $apiKey, string $model, string $system, string $text, string $effort): array
|
||||
{
|
||||
$schema = self::schema();
|
||||
$lastError = null;
|
||||
// One repetition when the answer does not fit the schema, then the message goes to the landlord.
|
||||
for ($attempt = 1; $attempt <= 2; $attempt++) {
|
||||
$result = $this->client->structured($apiKey, $model, $system, $text, $schema, $effort);
|
||||
$lastError = $this->violation($result['data'], $schema);
|
||||
if ($lastError === null) {
|
||||
return ['data' => $result['data'], 'model' => $result['model']];
|
||||
}
|
||||
}
|
||||
|
||||
throw new ExtractionFailed('Antwort passt nicht zum Schema: '.$lastError);
|
||||
}
|
||||
|
||||
/**
|
||||
* The first deviation of the answer from the schema, or null.
|
||||
*
|
||||
* @param array<string, mixed> $data
|
||||
* @param array<string, mixed> $schema
|
||||
*/
|
||||
private function violation(array $data, array $schema): ?string
|
||||
{
|
||||
foreach ($schema['required'] as $key) {
|
||||
if (! array_key_exists($key, $data)) {
|
||||
return 'Feld '.$key.' fehlt';
|
||||
}
|
||||
}
|
||||
if (! is_array($data['facts']) || ! is_array($data['change_requests']) || ! is_array($data['uncertainties']) || ! is_string($data['intent'])) {
|
||||
return 'falsche Typen';
|
||||
}
|
||||
if (! in_array($data['intent'], $schema['properties']['intent']['enum'], true)) {
|
||||
return 'unbekannte Absicht';
|
||||
}
|
||||
foreach (['facts', 'change_requests'] as $list) {
|
||||
$item = $schema['properties'][$list]['items'];
|
||||
foreach ($data[$list] as $entry) {
|
||||
if (! is_array($entry) || array_diff($item['required'], array_keys($entry)) !== [] || ! in_array($entry['field'], $item['properties']['field']['enum'], true)) {
|
||||
return 'ungültiger Eintrag in '.$list;
|
||||
}
|
||||
if (! is_string($entry['value']) || ! is_string($entry['evidence']) || ($list === 'facts' && ! is_numeric($entry['confidence']))) {
|
||||
return 'falscher Typ in '.$list;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
private function messageText(InboundMessage $message): string
|
||||
{
|
||||
return 'Subject: '.$message->subject."\n\n".mb_substr((string) $message->body, 0, 20000);
|
||||
}
|
||||
|
||||
/**
|
||||
* Values on file, masked: enough to see whether something differs, not to learn the data.
|
||||
*/
|
||||
private function knownFields(Booking $booking): string
|
||||
{
|
||||
$known = [];
|
||||
foreach ([...array_keys(CaseRequirements::FIELDS), ...array_keys(CaseRequirements::OPTIONAL_FIELDS)] as $field) {
|
||||
$value = (string) CaseRequirements::value($booking, $field);
|
||||
if ($value === '') {
|
||||
continue;
|
||||
}
|
||||
$known[] = $field.'='.(str_starts_with($field, 'booking.') ? $value : mb_substr($value, 0, 1).str_repeat('*', max(1, mb_strlen($value) - 2)).mb_substr($value, -1));
|
||||
}
|
||||
|
||||
return $known === [] ? 'none' : implode('; ', $known);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,155 @@
|
||||
<?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 [];
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user