false, 'reason' => '', ); /** * Facts about the single call that just ran, before they are folded into the trace. * * @var array */ protected $call = array(); /** * Constructor. * * @param MYBOT_Settings $settings Settings. */ public function __construct( $settings ) { $this->settings = $settings; } /** * The trace of the most recent call, ready to be stored or shown. * * @param array $extra Extra keys merged on top of the recorded ones. * @return array */ public function trace( $extra = array() ) { $trace = array_merge( array( 'at' => time(), 'question' => '', 'cached' => false, 'sources' => array(), ), $this->trace, (array) $extra ); // Kept in step with the sentence beside it: three surfaces colour themselves from this. $trace['state'] = self::state( $trace ); return $trace; } /** * Decide whether RAG should be used for this question. * * In auto mode RAG is only enabled when the question seems to need in-depth * knowledge, so most greetings still take the fast path. * * Every branch records why it answered the way it did, because "RAG was not used" on its * own sends the reader to the wrong setting. * * @param string $question The question. * @param string $mode Mode requested by the client: auto, always, never. * @return bool */ public function should_use( $question, $mode = 'auto' ) { $this->trace = array( 'used' => false, 'reason' => '', ); if ( ! $this->settings->rag_available() ) { $this->trace['reason'] = $this->unavailable_reason(); return false; } /* * The knowledge lock overrides every mode, including `never` and the widget's own embed * attribute. The owner put a file on the server saying "answer only from this website", and * nothing set in a screen may quietly weaken that: without this branch, a site left on the * default `auto` would still answer greetings and short questions from the model's own * knowledge, which is the first of the two token leaks in docs/08 muc 6.45. * * It sits AFTER the availability check on purpose: when the store cannot be reached at all * the reason must be the real one, and the caller refuses rather than answering from outside * knowledge. */ if ( class_exists( 'MYBOT_Knowledge_Lock' ) && MYBOT_Knowledge_Lock::is_active() ) { $this->trace['used'] = true; $this->trace['reason'] = __( 'The knowledge lock is on, so the knowledge base is always searched.', 'aihouse' ); return true; } $configured = (string) $this->settings->get( 'rag_mode', 'auto' ); if ( 'never' === $mode || 'never' === $configured ) { $this->trace['reason'] = ( 'never' === $configured ) ? __( 'The RAG tab says never to use the knowledge base.', 'aihouse' ) : __( 'The widget was embedded for quick answers only.', 'aihouse' ); return false; } if ( 'always' === $mode || 'always' === $configured ) { $this->trace['used'] = true; $this->trace['reason'] = ( 'always' === $configured ) ? __( 'The RAG tab says always to use the knowledge base.', 'aihouse' ) : __( 'The widget was embedded for deep answers.', 'aihouse' ); return true; } $question = trim( (string) $question ); $length = MYBOT_Chunker::length( $question ); // Very short questions are usually greetings and need no lookup. if ( $length < 15 ) { $this->trace['reason'] = __( 'The question is very short, so it was treated as small talk.', 'aihouse' ); return false; } $lower = function_exists( 'mb_strtolower' ) ? mb_strtolower( $question, 'UTF-8' ) : strtolower( $question ); // Vietnamese signals are matched as substrings, because the language has no // reliable word boundaries for this purpose. $signals = array( 'tại sao', 'như thế nào', 'làm sao', 'hướng dẫn', 'quy trình', 'chính sách', 'bảo hành', 'so sánh', 'khác gì', 'có được', 'thủ tục', 'điều kiện', 'thông tin', 'giá', 'phí', 'thời gian', 'địa chỉ', 'liên hệ', ); foreach ( $signals as $signal ) { if ( false !== strpos( $lower, $signal ) ) { $this->trace['used'] = true; $this->trace['reason'] = sprintf( /* translators: %s: the keyword that was found in the question */ __( 'The question contains the keyword "%s".', 'aihouse' ), $signal ); return true; } } /* * English signals have to match on word boundaries. Substring matching would * make "how" match inside "show" and "fee" inside "coffee", sending greetings * through the vector search for no reason. */ $english_signals = array( 'why', 'how', 'guide', 'process', 'policy', 'policies', 'warranty', 'compare', 'comparison', 'difference', 'procedure', 'condition', 'conditions', 'information', 'price', 'pricing', 'cost', 'fee', 'fees', 'time', 'address', 'contact', 'return', 'refund', 'shipping', 'delivery', 'support', 'require', 'requirement', 'available', ); $pattern = '/\b(?:' . implode( '|', array_map( fn( $signal ) => preg_quote( $signal, '/' ), $english_signals ) ) . ')\b/iu'; if ( preg_match( $pattern, $question, $matched ) ) { $this->trace['used'] = true; $this->trace['reason'] = sprintf( /* translators: %s: the keyword that was found in the question */ __( 'The question contains the keyword "%s".', 'aihouse' ), $matched[0] ); return true; } /* * Word count is language-agnostic whereas character count is not: 60 characters * is a much longer question in Vietnamese than in English. Without this, an * English question of ordinary length would skip the knowledge base entirely. */ $words = preg_split( '/\s+/u', $question, -1, PREG_SPLIT_NO_EMPTY ); if ( is_array( $words ) && count( $words ) >= 8 ) { $this->trace['used'] = true; $this->trace['reason'] = sprintf( /* translators: %d: number of words in the question */ __( 'The question runs to %d words, long enough to need context.', 'aihouse' ), count( $words ) ); return true; } // Long, multi-clause questions usually need context. if ( $length > 60 ) { $this->trace['used'] = true; $this->trace['reason'] = __( 'The question is long enough to need context.', 'aihouse' ); return true; } $this->trace['reason'] = __( 'The question did not look like it needs the knowledge base. Set "When to use RAG" to Always to search for every question.', 'aihouse' ); return false; } /** * Why the knowledge base cannot be used at all. * * @return string */ protected function unavailable_reason() { $all = $this->settings->all(); if ( empty( $all['rag_enabled'] ) ) { return __( 'The knowledge base is switched off on the RAG tab.', 'aihouse' ); } if ( 'none' === (string) $this->settings->get( 'vector_store', 'none' ) ) { return __( 'No vector store is selected on the RAG tab.', 'aihouse' ); } if ( '' === $this->settings->secret( 'vector_key' ) ) { return __( 'The vector store API key is empty.', 'aihouse' ); } return __( 'The embedding API key is empty, so a question cannot be turned into a vector.', 'aihouse' ); } /** * Retrieve the relevant chunks using the saved threshold. * * @param string $question The question. * @return array|WP_Error Array of content, score, and metadata. */ public function retrieve( $question ) { $chunks = $this->retrieve_with( $question, (float) $this->settings->get( 'rag_min_score', 0.35 ), (int) $this->settings->get( 'rag_top_k', 4 ) ); /* * The call facts are folded into the trace here and not inside retrieve_with(): the * diagnostic screen probes the same question with the threshold removed, and that * second call must not overwrite what the chat itself did. */ $this->trace = array_merge( $this->trace, $this->call, array( 'attempted' => true ) ); return $chunks; } /** * Retrieve the relevant chunks with an explicit threshold. * * The vector function filters below the threshold in SQL, so an empty result cannot tell * "the table holds no vectors" from "every vector scored under the bar". Asking again with * the threshold removed is the only way to tell those two apart, and they need opposite * fixes — reindex, or lower Minimum score. * * @param string $question The question. * @param float $min_score Score threshold. * @param int $top_k Maximum number of chunks. * @return array|WP_Error Array of content, score, and metadata. */ public function retrieve_with( $question, $min_score, $top_k ) { $this->call = array( 'min_score' => (float) $min_score, 'top_k' => max( 1, (int) $top_k ), 'matched' => 0, 'chunks' => 0, 'top_score' => null, 'error' => '', ); $embedder = MYBOT_LLM_Factory::embedding_provider( $this->settings ); if ( is_wp_error( $embedder ) ) { return $this->failed( $embedder ); } $this->call['model'] = (string) $this->settings->embedding_model(); $vectors = $embedder->embed( array( $question ), $this->call['model'] ); if ( is_wp_error( $vectors ) ) { return $this->failed( $vectors ); } // reset() rather than [0]: one text was sent, so the answer is the first vector whichever // key the provider labelled it with. $vector = is_array( $vectors ) ? reset( $vectors ) : null; if ( empty( $vector ) || ! is_array( $vector ) ) { return $this->failed( new WP_Error( 'mybot_embedding_empty', __( 'Could not generate a vector for the question.', 'aihouse' ) ) ); } $this->call['dims'] = count( $vector ); $store = MYBOT_Vector_Factory::make( $this->settings ); if ( is_wp_error( $store ) ) { return $this->failed( $store ); } $results = $store->query( $vector, $this->call['top_k'], $this->call['min_score'] ); if ( is_wp_error( $results ) ) { return $this->failed( $results ); } $this->call['matched'] = count( (array) $results ); $chunks = array_values( array_filter( (array) $results, function ( $item ) { return ! empty( $item['content'] ); } ) ); $this->call['chunks'] = count( $chunks ); $this->call['top_score'] = self::best_score( $chunks ); return $chunks; } /** * Embed a chunk that is already in the store and search for it with that vector. * * The strongest check available without re-indexing, and the one that tells apart the two * reasons a question can match nothing: * * - the chunk finds itself at ~1.0 -> the store and the query share one embedding model, * so the content simply does not answer the question; * - the chunk scores far lower -> the store was filled by a different model, and lowering * the threshold would only start returning unrelated text. * * @param string $content Stored chunk content. * @param string $expect_id The ID that chunk is stored under. * @return array|null Array with score, id and same; null when the check could not run. */ public function roundtrip( $content, $expect_id = '' ) { $content = trim( (string) $content ); if ( '' === $content ) { return null; } $matches = $this->retrieve_with( $content, 0.0, 1 ); if ( is_wp_error( $matches ) || empty( $matches[0] ) || ! is_array( $matches[0] ) ) { return null; } $top = $matches[0]; $id = isset( $top['id'] ) ? (string) $top['id'] : ''; return array( 'score' => isset( $top['score'] ) ? (float) $top['score'] : 0.0, 'id' => $id, 'same' => ( '' !== (string) $expect_id && $id === (string) $expect_id ), ); } /** * Whether a trace carries a round trip that failed to recognise the store's own text. * * @param array $trace Trace. * @return bool */ public static function roundtrip_failed( $trace ) { $trace = is_array( $trace ) ? $trace : array(); if ( ! isset( $trace['roundtrip']['score'] ) || null === $trace['roundtrip']['score'] ) { return false; } return ( (float) $trace['roundtrip']['score'] ) < self::SELF_MATCH_MIN; } /** * Records a failed call and hands the error back untouched. * * @param WP_Error $error Error. * @return WP_Error */ protected function failed( $error ) { $this->call['error'] = (string) $error->get_error_message(); return $error; } /** * Score of the best chunk in a result list. * * @param array $chunks Chunks. * @return float|null Null when no chunk carries a score. */ public static function best_score( $chunks ) { $best = null; foreach ( (array) $chunks as $chunk ) { if ( ! is_array( $chunk ) || ! isset( $chunk['score'] ) ) { continue; } $score = (float) $chunk['score']; if ( null === $best || $score > $best ) { $best = $score; } } return $best; } /** * One sentence explaining a trace, shared by the chat log, the test button and the * settings screen. * * @param array $trace Trace. * @return string */ public static function describe( $trace ) { $trace = is_array( $trace ) ? $trace : array(); if ( ! empty( $trace['error'] ) ) { return sprintf( /* translators: %s: error message returned by the embedding provider or the vector store */ __( 'The lookup failed before it could search: %s', 'aihouse' ), (string) $trace['error'] ); } if ( ! empty( $trace['cached'] ) ) { return __( 'The reply came from the answer cache; the sources saved with it are repeated below.', 'aihouse' ); } if ( empty( $trace['attempted'] ) ) { return sprintf( /* translators: %s: why the knowledge base was not consulted */ __( 'The knowledge base was not consulted: %s', 'aihouse' ), isset( $trace['reason'] ) ? (string) $trace['reason'] : '' ); } $chunks = isset( $trace['chunks'] ) ? (int) $trace['chunks'] : 0; $min = self::format_score( isset( $trace['min_score'] ) ? $trace['min_score'] : 0 ); if ( $chunks > 0 ) { return sprintf( /* translators: 1: number of chunks, 2: score of the best chunk, 3: the Minimum score setting */ __( 'The lookup worked: %1$d chunks cleared the Minimum score of %3$s, and the best scored %2$s.', 'aihouse' ), $chunks, self::format_score( isset( $trace['top_score'] ) ? $trace['top_score'] : 0 ), $min ); } /* * The "rows" key exists only when the lookup was measured with the threshold removed, * which is what the test button does. An ordinary chat lookup that matched nothing * cannot know whether the table is empty or every vector sits under the bar, so it must * not claim either: it points at the button instead. */ if ( array_key_exists( 'rows', $trace ) ) { $best = ( isset( $trace['best_score'] ) && null !== $trace['best_score'] ) ? self::format_score( $trace['best_score'] ) : ''; /* * The round trip is checked before the score is discussed: if the store cannot even * match its own text, then the score of the closest chunk says nothing about how * relevant the content is, and advising a lower threshold would send the reader to * fix the one thing that cannot help. */ if ( self::roundtrip_failed( $trace ) ) { return sprintf( /* translators: 1: score a stored chunk got against itself, 2: score of the closest chunk to the question */ __( 'The knowledge base cannot match its own text: a stored chunk scored only %1$s against itself, so the vectors in the store do not belong to the embedding model selected now — they were either built by a different model or paired with the wrong chunks when they were written. No threshold can fix that. Check the Embedding model on the RAG tab, then press Re-index everything (Index missing items skips content that has not changed). The closest chunk to this question scored %2$s.', 'aihouse' ), self::format_score( $trace['roundtrip']['score'] ), ( '' !== $best ) ? $best : '—' ); } if ( '' !== $best ) { if ( ! empty( $trace['roundtrip']['score'] ) ) { return sprintf( /* translators: 1: score of the closest chunk, 2: the Minimum score setting, 3: the round trip score */ __( 'Nothing cleared the Minimum score of %2$s: the closest chunk scored %1$s. The vectors themselves are fine — a stored chunk matched itself at %3$s — so this question has no matching content. Index the pages that answer it, or ask with words that appear in your content.', 'aihouse' ), $best, $min, self::format_score( $trace['roundtrip']['score'] ) ); } return sprintf( /* translators: 1: score of the closest chunk, 2: the Minimum score setting */ __( 'Nothing cleared the Minimum score of %2$s: the closest chunk scored %1$s. Lower Minimum score on the RAG tab, or index the knowledge again if that score looks wrong.', 'aihouse' ), $best, $min ); } return __( 'The vector store returned no rows at all, so the knowledge base looks empty. Check that indexing finished and that the table holds vectors.', 'aihouse' ); } return sprintf( /* translators: %s: the Minimum score setting */ __( 'Nothing cleared the Minimum score of %s, and the score of the closest chunk was not measured. Press "Look this up" on the RAG tab to see that score.', 'aihouse' ), $min ); } /** * How a trace should read at a glance: ok, error or info. * * Defined once because three surfaces colour themselves from it — the settings card, the log * box and the JSON the buttons read. A red box next to "the lookup worked" would be its own * kind of wrong label, which is the lesson of 6.20. * * @param array $trace Trace. * @return string One of 'ok', 'error', 'info'. */ public static function state( $trace ) { $trace = is_array( $trace ) ? $trace : array(); if ( ! empty( $trace['error'] ) || self::roundtrip_failed( $trace ) ) { return 'error'; } return ( isset( $trace['chunks'] ) && (int) $trace['chunks'] > 0 ) ? 'ok' : 'info'; } /** * Shortens a question so the trace stays readable. * * Defined once and used by both routes that record a trace: two copies of this would be * the same mistake as the duplicated defaults that hid three earlier bugs. * * @param string $text Text. * @param int $max Maximum length. * @return string */ public static function shorten( $text, $max = 120 ) { $text = trim( preg_replace( '/\s+/u', ' ', (string) $text ) ); return MYBOT_Chunker::length( $text ) > $max ? MYBOT_Chunker::slice( $text, 0, $max ) . '…' : $text; } /** * Formats a similarity score for display, honouring the site locale. * * @param mixed $score Score. * @return string */ public static function format_score( $score ) { return number_format_i18n( (float) $score, 2 ); } /** * Assemble the retrieved chunks into a context block for the LLM. * * @param array $chunks Retrieved chunks. * @return string */ public function build_context( $chunks ) { $max = (int) $this->settings->get( 'rag_max_context', 6000 ); $parts = array(); $used = 0; foreach ( (array) $chunks as $index => $chunk ) { $content = trim( (string) $chunk['content'] ); $length = MYBOT_Chunker::length( $content ); if ( ( $used + $length ) > $max ) { $remaining = $max - $used; if ( $remaining < 200 ) { break; } $content = MYBOT_Chunker::slice( $content, 0, $remaining ); $length = MYBOT_Chunker::length( $content ); } $title = isset( $chunk['metadata']['title'] ) ? (string) $chunk['metadata']['title'] : ''; $url = isset( $chunk['metadata']['url'] ) ? (string) $chunk['metadata']['url'] : ''; $header = sprintf( '[Source %d]', $index + 1 ); if ( '' !== $title ) { $header .= ' ' . $title; } if ( '' !== $url ) { $header .= ' — ' . $url; } $parts[] = $header . "\n" . $content; $used += $length; if ( $used >= $max ) { break; } } return implode( "\n\n---\n\n", $parts ); } /** * List of sources used, returned to the client for citation. * * ONE ROW PER DOCUMENT, NOT PER CHUNK (1.22.6). * * A long page is stored as several chunks, and retrieval usually returns several of them for one question — so this * method used to hand the widget the same title four times. The owner photographed exactly that: one answer with * "Comprehensive SEO Knowledge Base for AI Customer Support" printed four times under **Sources**, which reads as * four documents and makes a correct answer look padded. The reader cannot see that it is one page, and the widget * cannot know it either: the payload said four. * * So the list is de-duplicated by DOCUMENT — the id the indexer wrote into `metadata.source_id`, then the URL, then * the title — and the FIRST occurrence is kept, because retrieved chunks arrive in score order and the first is the * best evidence for the answer. The remaining chunks of the same document are still in `$chunks` and still reach the * model as context; they are simply not four citations. * * What this deliberately does NOT do: merge two documents that merely share a title. That only happens when neither * an id nor a URL is available, which means the chunk did not come through the indexer, and inventing a merge there * would hide a broken source rather than tidy it. * * @param array $chunks Retrieved chunks. * @return array */ public function build_sources( $chunks ) { $sources = array(); $seen = array(); foreach ( (array) $chunks as $chunk ) { $metadata = isset( $chunk['metadata'] ) && is_array( $chunk['metadata'] ) ? $chunk['metadata'] : array(); $title = isset( $metadata['title'] ) ? (string) $metadata['title'] : ''; $url = isset( $metadata['url'] ) ? (string) $metadata['url'] : ''; $key = $this->source_key( $metadata, $title, $url ); if ( '' !== $key ) { if ( isset( $seen[ $key ] ) ) { continue; } $seen[ $key ] = true; } $sources[] = array( 'title' => $title, 'url' => $url, 'score' => isset( $chunk['score'] ) ? round( (float) $chunk['score'], 4 ) : 0.0, ); } return $sources; } /** * The identity of the DOCUMENT a chunk came from, for de-duplication. * * Returns '' when the chunk carries nothing that identifies it — an empty key means "do not merge", which keeps a * source with no id, no URL and no title visible instead of silently collapsing several of them into one. * * @param array $metadata Chunk metadata. * @param string $title Title, already read. * @param string $url URL, already read. * @return string */ protected function source_key( $metadata, $title, $url ) { if ( isset( $metadata['source_id'] ) && (int) $metadata['source_id'] > 0 ) { return 'id:' . (int) $metadata['source_id']; } if ( '' !== trim( $url ) ) { return 'url:' . strtolower( trim( $url ) ); } if ( '' !== trim( $title ) ) { return 'title:' . strtolower( trim( $title ) ); } return ''; } }