LLM Çıktısını Şemaya Zorlamak: Serbest Metinden Güvenilir JSON’a

const SEMA = [
    'baslik'     => ['tip' => 'string', 'zorunlu' => true,  'maks' => 120],
    'ozet'       => ['tip' => 'string', 'zorunlu' => true,  'maks' => 300],
    'duygu'      => ['tip' => 'enum',   'zorunlu' => true,  'degerler' => ['olumlu', 'notr', 'olumsuz']],
    'etiketler'  => ['tip' => 'array',  'zorunlu' => false, 'maks' => 8],
];

function semaMetni(array $sema): string
{
    $satirlar = [];
    foreach ($sema as $alan => $k) {
        $ek = $k['tip'] === 'enum' ? ' (yalnızca: ' . implode(', ', $k['degerler']) . ')' : '';
        $satirlar[] = "- {$alan}: {$k['tip']}" . ($k['zorunlu'] ? ' [zorunlu]' : ' [isteğe bağlı]') . $ek;
    }

    return "Yanıtı SADECE geçerli JSON olarak ver. Açıklama, kod bloğu işareti veya "
        . "ek metin ekleme. Alanlar:\n" . implode("\n", $satirlar);
}

function jsonAyikla(string $ham): ?array
{
    $metin = trim($ham);

    // ```json ... ``` sarmalayıcısını temizle
    if (preg_match('/```(?:json)?\s*(.+?)```/s', $metin, $m) === 1) {
        $metin = trim($m[1]);
    }

    // Baştaki/sondaki açıklama cümlelerini at: ilk { ile son } arasını al
    $bas = strpos($metin, '{');
    $son = strrpos($metin, '}');
    if ($bas === false || $son === false || $son < $bas) {
        return null;
    }

    $veri = json_decode(substr($metin, $bas, $son - $bas + 1), true);

    return is_array($veri) ? $veri : null;
}

function semayaGoreDogrula(array $veri, array $sema): array
{
    $hatalar = [];

    foreach ($sema as $alan => $k) {
        $var = array_key_exists($alan, $veri);

        if (! $var) {
            if ($k['zorunlu']) {
                $hatalar[] = "'{$alan}' alanı eksik.";
            }
            continue;
        }

        $deger = $veri[$alan];

        if ($k['tip'] === 'enum' && ! in_array($deger, $k['degerler'], true)) {
            $hatalar[] = "'{$alan}' değeri geçersiz: " . var_export($deger, true);
        }
        if ($k['tip'] === 'string' && ! is_string($deger)) {
            $hatalar[] = "'{$alan}' metin olmalı.";
        }
        if ($k['tip'] === 'array' && ! is_array($deger)) {
            $hatalar[] = "'{$alan}' dizi olmalı.";
        }
        if (isset($k['maks']) && is_string($deger) && mb_strlen($deger) > $k['maks']) {
            $hatalar[] = "'{$alan}' en fazla {$k['maks']} karakter olmalı.";
        }
    }

    return $hatalar;
}

function yapilandirilmisIste(LlmIstemci $llm, string $girdi, array $sema): ?array
{
    $istek  = semaMetni($sema) . "\n\nMetin:\n" . $girdi;
    $yanit  = $llm->uret($istek, ['temperature' => 0.1]);   // düşük sıcaklık = kararlı yapı
    $veri   = jsonAyikla($yanit);
    $hatalar = $veri === null ? ['Yanıt geçerli JSON değil.'] : semayaGoreDogrula($veri, $sema);

    if (! $hatalar) {
        return $veri;
    }

    // Tek onarım turu: hatayı açıkça söyle
    $onarim = $istek . "\n\nÖnceki yanıtın şu hataları içeriyordu:\n- "
        . implode("\n- ", $hatalar) . "\nYalnızca düzeltilmiş JSON'u döndür.";

    $veri = jsonAyikla($llm->uret($onarim, ['temperature' => 0.0]));

    return ($veri !== null && ! semayaGoreDogrula($veri, $sema)) ? $veri : null;
}