<?php
// SPDX-License-Identifier: GPL-3.0-or-later
declare(strict_types=1);

namespace Aiwend\Knowledge;

/**
 * Why knowledge retrieval failed, as a closed, typed set (never derived from exception messages). It is internal: it goes into
 * the audit row's detail and into ChatException::$failure, and it decides the public mapping in one place (publicError()).
 * Today every case is the public 503 "knowledge_failed". Genuine budget exhaustion has a prepared HTTP 429 mapping that stays
 * dormant (`$budgetAs429` is false everywhere) until remote embeddings are enabled and the owner approves it.
 */
enum RetrievalFailure: string
{
    /** A usage limit of the site or conversation is genuinely exhausted (reserve() refused with BudgetExceededException). */
    case Budget = 'budget';
    /** The spending kill switch is on: an owner action, not an exhausted limit. */
    case Paused = 'paused';
    /** The provider or network failed or throttled (unavailable, timeout, rate limit, content filter). */
    case Provider = 'provider';
    /** Authentication, invalid request, unsupported model or missing operation context: an administrator must fix the setup. */
    case Configuration = 'configuration';
    /** The cost of a dispatched request is not known (missing usage, unknown outcome): the hold stays, nothing is released. */
    case Uncertain = 'uncertain';
    /** The provider answered with an unexpected model, batch, vector shape or dimension. */
    case Model = 'model';
    /** The stored index cannot be used with the active embedder (wrong dimension, incompatible vectors). */
    case Index = 'index';
    /** The input to embed was invalid (empty, too long, bad encoding). */
    case Input = 'input';
    /** The same embedding operation was already attempted; never charged or sent twice. */
    case Duplicate = 'duplicate';
    /** The database failed. */
    case Database = 'database';
    /** Anything else. */
    case Unknown = 'unknown';

    /** The only place that turns a typed failure into the public error. @return array{code:string, status:int} */
    public function publicError(bool $budgetAs429 = false): array
    {
        return $budgetAs429 && $this === self::Budget
            ? ['code' => 'usage_limit_reached', 'status' => 429]
            : ['code' => 'knowledge_failed', 'status' => 503];
    }

    /** Exhausted limit, not a halted kill switch, provider failure or indexing problem. */
    public function isBudgetExhaustion(): bool
    {
        return $this === self::Budget;
    }

    public static function classify(\Throwable $e): self
    {
        if ($e instanceof ExtractionException && $e->failure !== null) {
            return $e->failure;
        }
        if ($e instanceof EmbeddingResponseException) {
            return $e->failure;
        }
        if ($e instanceof \Aiwend\Db\DatabaseException) {
            return self::Database;
        }
        if ($e instanceof \UnexpectedValueException) {
            return self::Index; // VectorCodec::decode rejects a stored vector of the wrong length
        }
        return self::Unknown;
    }
}