Files
fewo-stommer/app/Communication/Extraction/MessageExtractor.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

162 lines
6.9 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\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);
}
}