Files
fewo-stommer/app/Communication/Extraction/MessageExtractor.php
LarsandClaude Opus 5.5 6862dec201
Deploy FeWo mit PipelineManager / deploy (push) Successful in 5m11s
v0.11 U6: Bring your own key für die KI-Auswertung (Anthropic, OpenRouter)
- Jeder Mandant verbindet unter „System › KI-Anbindung“ seinen eigenen
  Zugang: Anbieter (Anthropic oder OpenRouter), API-Schlüssel, Modell für
  die erste Auswertung und für die Prüfung – keine Modellkennung im Code,
  kein zentraler Betreiberschlüssel (FEWO_AI_API_KEY entfällt).
- Gespeichert im bestehenden TenantService (ai_guest_mail): Schlüssel
  verschlüsselt, nie wieder angezeigt, nie in Meldungen; Anbieter/Modelle
  in settings, Prüfergebnis in check_status/check_message/checked_at.
- Feste Endpunkte je Anbieter (AiProvider), nicht konfigurierbar.
  OpenRouter mit response_format json_schema (strict) und
  provider.require_parameters.
- „Verbindung prüfen“ testet beide Modelle. Ein abgelehnter Zugang
  (401/402/403) schaltet die Auswertung für den Mandanten ab, meldet es im
  Postfach der Verwaltung; Nachrichten bleiben zur Prüfung im Posteingang.
- Zweistufige Extraktion und ihre Sicherheitsregeln unverändert.
- Zielarchitektur §3.8, Umsetzungsplan U6, Bericht, Drehbuch, Status.

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

163 lines
7.0 KiB
PHP
Raw Permalink 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 as configured in the landlord's own access. 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(AiAccess $access, InboundMessage $message, Booking $booking): array
{
return $this->call($access, $access->smallModel, $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(AiAccess $access, InboundMessage $message, Booking $booking, array $first): array
{
return $this->call($access, $access->reviewModel, $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(AiAccess $access, 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($access, $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);
}
}