<?php
if (!defined('ABSPATH')) {
    exit;
}

/**
 * AnswerRails_Retrieval — retrieval engine resolution (#92).
 *
 * The single source of truth for which engine grounds chat turns. Kept as
 * its own micro-class (rather than a method on AnswerRails_Utils) so the
 * resolver is exercised for REAL by the unit suite — the test harness stubs
 * Utils as its canned-primitives boundary (debug sink, canned keys), and a
 * resolver living there would be shadowed by the stub, never tested.
 *
 * #89 full hybrid slots in behind this resolver later as better engine
 * internals ('local' gains embeddings invisibly); this class is the seam.
 */
class AnswerRails_Retrieval {

    /**
     * Hard ceiling for retrieval depth (#140; #106 owns retuning). The two
     * classic ceiling arguments
     * have different jobs under BYOK:
     *
     * - COST is a DEFAULT argument, not a ceiling argument: depth is a
     *   spend dial on the customer's own bill (~1,800-char chunks ≈
     *   450–500 tokens each; 20 ≈ 9–10k injected tokens/turn, 30 ≈
     *   13–15k). The option default (20) is the sensible operating point;
     *   overclocking is the owner's informed choice — the same philosophy
     *   that rejected quantity caps (decision 23 D7).
     * - QUALITY is the real ceiling argument, and it is already bounded by
     *   the 0.30 relevance threshold: every depth only admits chunks that
     *   cleared it, so the residual risk at 21–30 is attention dilution —
     *   a legitimate thing to let an owner experiment with deliberately.
     *   If the answer isn't in the top ~30 relevant chunks, the fix is
     *   retrieval quality (#89), not a bigger scoop — hence a hard ceiling
     *   remains.
     */
    public const MAX_RETRIEVAL_DEPTH = 30;

    /**
     * Default retrieval depth — the untuned-safe value (#140, #174):
     *
     * - Depth is a spend dial on the customer's own provider bill (BYOK) —
     *   the default errs cheap; deeper grounding is a deliberate choice via
     *   the `answerrails_retrieval_depth` filter.
     * - The 0.30 relevance threshold admits chunks in DESCENDING relevance
     *   order, so added depth mostly admits lower-relevance material —
     *   5 is the untuned-safe operating point; past it, returns diminish
     *   and attention dilution begins (MAX_RETRIEVAL_DEPTH's argument).
     */
    public const DEFAULT_DEPTH = 5;

    /**
     * Supplementary depth for the focus-resolution second pass (#142) —
     * diligence costs more. SUPPLEMENTARY, never shared: pass 1 stays
     * byte-identical to today, and a triggered turn spends up to this much
     * more on the FOCUSED query (the mapping's output term). The mechanism
     * is universal; what varies is REACH, never intelligence. #106's bench
     * owns retuning.
     */
    public const SECOND_PASS_DEPTH = 5;

    /**
     * Supplementary depth for the follow-up context pass (#364,
     * FOLLOW_UP_RETRIEVAL_DESIGN D2, Amendment A1/Q1). SUPPLEMENTARY, never
     * shared: pass 1 keeps its full retrieval_depth() and stays
     * byte-identical, and the context pass appends up to this many more rows
     * after pass 1 and the focus pass. A shared cap was measured to inject
     * ZERO context rows whenever pass 1 returns a full set (§1.1 saturation
     * evidence) — and on a lexical index of any real size it nearly always
     * does, because common words match.
     *
     * Why 3, not SECOND_PASS_DEPTH's 5: lexical applies no threshold, so
     * every context row that survives dedup is injected. Three bounds the
     * guaranteed extra material at ~1.4k tokens per non-first turn
     * (~1,800-char chunks ≈ 450–500 tokens each) on the owner's BYOK bill;
     * in both measured windows the context-bearing rows ranked first and
     * second. #106's bench owns retuning.
     */
    public const CONTEXT_PASS_DEPTH = 3;

    /**
     * Character cap (#364 D3) for the prior visitor turn (END kept — the
     * end of a turn is nearest the follow-up) and for the admitted assistant
     * excerpt (START kept — where the direct answer sits), each cut at
     * whitespace with mb_substr. Natural-language fulltext SUMS term
     * weights, so an uncapped prior (a pasted paragraph) would outweigh the
     * current turn's own terms. 300 characters ≈ 50 words: several times a
     * typical chat turn, a sixth of a chunk.
     */
    public const CONTEXT_PRIOR_CHARS = 300;

    /**
     * Resolve the retrieval depth — THE single depth authority (#140 D8,
     * the Logger::logging_mode() pattern from #109: raw reads of the depth
     * option for depth decisions are a regression, and a test pins the
     * known call site).
     *
     * E3 extension point (#174): `answerrails_retrieval_depth` filters
     * DEFAULT_DEPTH; the result is clamped to [1, MAX_RETRIEVAL_DEPTH]
     * AFTER the filter, so no consumer can exceed the ceiling. With nothing
     * hooked, the default (5) applies.
     *
     * Both engines inherit this — the resolved value feeds vector search
     * and the local lexical paths alike.
     */
    public static function retrieval_depth(): int {
        return max(1, min(self::MAX_RETRIEVAL_DEPTH, (int) apply_filters('answerrails_retrieval_depth', self::DEFAULT_DEPTH)));
    }

    /**
     * Resolve the active retrieval engine.
     *
     * The `reason` distinguishes the SUPPORTED keyless local mode
     * ('no_key'/'no_store' — normal operation, no alarm) from the explicit
     * testing override ('option' while vector is fully configured —
     * surfaced unmissably in the admin, see override_active()).
     *
     * @return array{engine: string, reason: string}
     *               engine: 'vector'|'local';
     *               reason: 'option'|'no_key'|'no_store'|'default'
     */
    public static function engine(): array {
        if ('local' === (string) get_option('answerrails_retrieval_engine', 'auto')) {
            return array('engine' => 'local', 'reason' => 'option');
        }

        if ('' === AnswerRails_Utils::get_api_key_for('openai')) {
            return array('engine' => 'local', 'reason' => 'no_key');
        }

        if ('' === (string) get_option('answerrails_knowledge_vector_store_id', '')) {
            return array('engine' => 'local', 'reason' => 'no_store');
        }

        return array('engine' => 'vector', 'reason' => 'default');
    }

    /**
     * Whether the explicit Local override is active WHILE vector search is
     * fully configured — i.e. testing mode, not supported keyless local
     * mode. Drives the unmissable admin indicator + notice (#92).
     */
    public static function override_active(): bool {
        $resolved = self::engine();

        return 'option' === $resolved['reason']
            && '' !== AnswerRails_Utils::get_api_key_for('openai')
            && '' !== (string) get_option('answerrails_knowledge_vector_store_id', '');
    }

    /**
     * A chat message's text — THE one content-parts extraction (#364 D3):
     * array content joins its `text` parts / string parts with a space;
     * string content is used as-is; the result is trimmed. Role-agnostic —
     * callers choose the role. A non-array message has no text.
     *
     * @param mixed $message One `$messages` entry.
     */
    public static function message_text($message): string {
        if (!is_array($message)) {
            return '';
        }
        $content = $message['content'] ?? '';
        if (is_array($content)) {
            $parts = array();
            foreach ($content as $part) {
                if (is_array($part) && isset($part['text'])) {
                    $parts[] = (string) $part['text'];
                } elseif (is_string($part)) {
                    $parts[] = $part;
                }
            }
            $content = implode(' ', $parts);
        }
        return trim((string) $content);
    }

    /**
     * Remove contact details from prior-turn text before it joins a
     * retrieval query (#364 D7). Every email-shaped match is removed
     * (valid or not — broader than capture, which keeps only is_email()
     * survivors), and every phone-shaped match carrying 7+ digits; each is
     * replaced by a single space, then the result is trimmed. One pass
     * suffices: each phone match is a maximal run of its character class
     * (a leading `+` can only open one), so a removal cannot bring digit
     * runs together, and emails are removed before phones.
     *
     * The grammar is AT LEAST AS BROAD as
     * AnswerRails_Pro_Escalations::extract_contact()
     * (pro/class-answerrails-pro-escalations.php:897): spaces, hyphens,
     * periods, parentheses and a leading `+` all separate phone digits.
     * It lives free-side because the free plugin ships without `pro/`, and
     * it deliberately does not reference the Pro pattern — parity is pinned
     * BEHAVIOURALLY by test (extract_contact() on scrubbed text finds
     * nothing). Why it exists: contact-capture turns skip retrieval, so
     * their text never reached the vector-search endpoint; the follow-up
     * window would otherwise send it there on a later miss turn.
     */
    public static function scrub_contact(string $text): string {
        $text = (string) preg_replace('/[a-z0-9._%+\-]+@[a-z0-9.\-]+\.[a-z]{2,}/i', ' ', $text);
        $text = (string) preg_replace_callback(
            '/\+?\d[\d\s().\-]{6,}\d/',
            static function (array $m): string {
                return strlen((string) preg_replace('/\D+/', '', $m[0])) >= 7 ? ' ' : $m[0];
            },
            $text
        );

        return trim($text);
    }

    /**
     * Build the follow-up context-pass query (#364 D3, Amendment A1).
     * Pure: reads nothing but its argument.
     *
     * - current: the last `user` entry with text — unchanged, uncapped, NOT
     *   scrubbed (pass 1 already sends it; D2 keeps pass 1 byte-identical).
     * - prior: the nearest EARLIER `user` entry with text — ONE turn only
     *   (A1/Q4: if it is empty after the scrub, there is no prior; nothing
     *   further back is consulted). Scrubbed, then capped from its END.
     * - assistant: the nearest `assistant` entry between prior and current
     *   with text (A1/Q2(B)) — scrubbed, then capped from its START.
     *
     * A turn is non-first iff the scrubbed prior is non-empty; an assistant
     * answer alone never makes it so. The query joins the non-empty parts
     * in conversation order (prior, assistant, current). `turns` counts
     * prior VISITOR turns only — the assistant excerpt is never counted.
     *
     * @param array $messages The normalised chat history.
     * @return array{query: string, turns: int}
     */
    public static function context_query(array $messages): array {
        $none    = array('query' => '', 'turns' => 0);
        $entries = array_values($messages);

        $current = -1;
        for ($i = count($entries) - 1; $i >= 0; $i--) {
            if (self::has_role($entries[$i], 'user') && '' !== self::message_text($entries[$i])) {
                $current = $i;
                break;
            }
        }
        if ($current < 0) {
            return $none;
        }

        $prior_at = -1;
        for ($i = $current - 1; $i >= 0; $i--) {
            if (self::has_role($entries[$i], 'user') && '' !== self::message_text($entries[$i])) {
                $prior_at = $i;
                break;
            }
        }
        if ($prior_at < 0) {
            return $none;
        }

        $prior = self::cap_keep_end(self::scrub_contact(self::message_text($entries[$prior_at])));
        if ('' === $prior) {
            return $none;
        }

        $assistant = '';
        for ($i = $current - 1; $i > $prior_at; $i--) {
            if (self::has_role($entries[$i], 'assistant') && '' !== self::message_text($entries[$i])) {
                $assistant = self::cap_keep_start(self::scrub_contact(self::message_text($entries[$i])));
                break;
            }
        }

        $parts = array_filter(
            array($prior, $assistant, self::message_text($entries[$current])),
            static function (string $part): bool {
                return '' !== $part;
            }
        );

        return array('query' => implode("\n", $parts), 'turns' => 1);
    }

    /**
     * Whether a `$messages` entry carries the given role (case-insensitive).
     *
     * @param mixed $message One `$messages` entry.
     */
    private static function has_role($message, string $role): bool {
        return is_array($message) && strtolower((string) ($message['role'] ?? '')) === $role;
    }

    /**
     * Cap to CONTEXT_PRIOR_CHARS keeping the END; a word cut by the
     * boundary is dropped whole (unless the tail has no whitespace at all,
     * when the hard cut stands).
     */
    private static function cap_keep_end(string $text): string {
        if (mb_strlen($text) <= self::CONTEXT_PRIOR_CHARS) {
            return $text;
        }
        $tail = mb_substr($text, -self::CONTEXT_PRIOR_CHARS);
        if (!self::is_space(mb_substr($text, -self::CONTEXT_PRIOR_CHARS - 1, 1))) {
            $trimmed = preg_replace('/^\S*\s/u', '', $tail, 1);
            if (is_string($trimmed) && $trimmed !== $tail) {
                $tail = $trimmed;
            }
        }
        return trim($tail);
    }

    /**
     * Cap to CONTEXT_PRIOR_CHARS keeping the START; a word cut by the
     * boundary is dropped whole (unless the head has no whitespace at all,
     * when the hard cut stands).
     */
    private static function cap_keep_start(string $text): string {
        if (mb_strlen($text) <= self::CONTEXT_PRIOR_CHARS) {
            return $text;
        }
        $head = mb_substr($text, 0, self::CONTEXT_PRIOR_CHARS);
        if (!self::is_space(mb_substr($text, self::CONTEXT_PRIOR_CHARS, 1))) {
            $trimmed = preg_replace('/\s\S*$/u', '', $head, 1);
            if (is_string($trimmed) && $trimmed !== $head) {
                $head = $trimmed;
            }
        }
        return trim($head);
    }

    /**
     * Whether a single character is whitespace (Unicode-aware).
     */
    private static function is_space(string $char): bool {
        return 1 === preg_match('/^\s$/u', $char);
    }
}