sanitize shape -> trim list/table limits -> * enforce the paragraph hard limit -> banned phrases -> preferred terms -> * unsupported numbers), because which steps run on the first pass vs. only * after the one allowed targeted retry differs by situation and that * sequencing decision belongs with the generator, not the validator. * * @package AIPT\Api\ContentStructure\Engine * @since 2.8.0 */ namespace AIPT\Api\ContentStructure\Engine; defined( 'ABSPATH' ) || exit; /** * Per-unit output validation primitives. */ class OutputValidator { /** * Fixed, non-configurable phrasing (English and Turkish) that says a * topic is not covered instead of actually answering it - exactly what * `Generators\Formula\FaqAssembly::NO_DATA_RULE` tells the model to do * instead (return no pairs for that group), never write. Deliberately * short: a long multi-language thesaurus would be guesswork dressed up * as detection, so this only catches the model stating its own * uncertainty in so many words, not every way a fabricated answer could * read. */ public const NO_DATA_HEDGE_PHRASES = array( 'not specified', 'not provided', 'not mentioned', 'does not specify', 'does not mention', 'unknown', 'belirtilmemiş', 'bilgi yer almamaktadır', ); /** * Match the model's raw decoded unit list against the expected ids. * * @param mixed $decoded_list Raw decoded list (expected: array of arrays, each with an 'id'). * @param string[] $expected_ids Ids the engine actually asked for, in any order. * @return array{byId: array, findings: array, missingIds: string[]} */ public function matchUnits( $decoded_list, array $expected_ids ): array { $by_id = array(); $findings = array(); $seen = array(); foreach ( (array) $decoded_list as $raw ) { if ( ! is_array( $raw ) || ! isset( $raw['id'] ) || ! is_string( $raw['id'] ) ) { $findings[] = $this->finding( 'invalid_shape', 'warning', __( 'The model returned a section with no usable id.', 'ai-product-tools' ) ); continue; } $id = $raw['id']; if ( ! in_array( $id, $expected_ids, true ) ) { /* translators: %s: the unexpected section id the model returned. */ $findings[] = $this->finding( 'unknown_section', 'info', sprintf( __( 'The model returned an unexpected section id "%s", which was discarded.', 'ai-product-tools' ), $id ), $id ); continue; } if ( isset( $seen[ $id ] ) ) { /* translators: %s: the section id the model returned more than once. */ $findings[] = $this->finding( 'duplicate_section', 'warning', sprintf( __( 'The model returned section "%s" more than once; only the first copy was kept.', 'ai-product-tools' ), $id ), $id ); continue; } $seen[ $id ] = true; $by_id[ $id ] = $raw; } $missing_ids = array_values( array_diff( $expected_ids, array_keys( $by_id ) ) ); foreach ( $missing_ids as $id ) { /* translators: %s: the expected section id the model did not return. */ $findings[] = $this->finding( 'missing_section', 'warning', sprintf( __( 'The model did not return section "%s".', 'ai-product-tools' ), $id ), $id ); } return array( 'byId' => $by_id, 'findings' => $findings, 'missingIds' => $missing_ids, ); } /** * Clean and shape-validate one unit's raw payload for its format. * Strips control characters and HTML tags, removes Markdown emphasis * and leading list markers, and collapses whitespace. Never trims to a * limit here (see trimToMax()/checkHardLimit()). * * @param array $raw Raw decoded unit object. * @param string $format 'paragraph' | 'bullets' | 'numbered' | 'table'. * @return array{ok:bool,heading:string,paragraphs:string[],items:string[],rows:array,findings:array} */ public function sanitizeUnit( array $raw, string $format ): array { $had_html = false; $clean = function ( $value ) use ( &$had_html ) { return $this->cleanField( $value, $had_html ); }; $heading = $clean( $raw['heading'] ?? '' ); $base = array( 'heading' => $heading, 'paragraphs' => array(), 'items' => array(), 'rows' => array() ); switch ( $format ) { case 'paragraph': if ( ! isset( $raw['paragraphs'] ) || ! is_array( $raw['paragraphs'] ) ) { return $base + array( 'ok' => false, 'findings' => array() ); } $paragraphs = $this->cleanList( $raw['paragraphs'], $clean ); return array_merge( $base, array( 'ok' => ! empty( $paragraphs ), 'paragraphs' => $paragraphs, 'findings' => $this->htmlFinding( $had_html ), ) ); case 'bullets': case 'numbered': if ( ! isset( $raw['items'] ) || ! is_array( $raw['items'] ) ) { return $base + array( 'ok' => false, 'findings' => array() ); } $items = $this->cleanList( $raw['items'], $clean ); return array_merge( $base, array( 'ok' => ! empty( $items ), 'items' => $items, 'findings' => $this->htmlFinding( $had_html ), ) ); case 'table': if ( ! isset( $raw['rows'] ) || ! is_array( $raw['rows'] ) ) { return $base + array( 'ok' => false, 'findings' => array() ); } $rows = array(); foreach ( $raw['rows'] as $row ) { if ( ! is_array( $row ) ) { continue; } $label = $clean( $row['label'] ?? '' ); $value = $clean( $row['value'] ?? '' ); if ( '' === $label && '' === $value ) { continue; } $rows[] = array( 'label' => $label, 'value' => $value ); } return array_merge( $base, array( 'ok' => ! empty( $rows ), 'rows' => $rows, 'findings' => $this->htmlFinding( $had_html ), ) ); default: return $base + array( 'ok' => false, 'findings' => array() ); } } /** * Deterministically trim a list (items or table rows) to its configured * maximum, keeping the first N. * * @param array $values Items or rows. * @param int $max Maximum allowed (<= 0 means "no limit"). * @return array{values:array,trimmed:bool,available:int} */ public function trimToMax( array $values, int $max ): array { $available = count( $values ); if ( $max <= 0 || $available <= $max ) { return array( 'values' => $values, 'trimmed' => false, 'available' => $available ); } return array( 'values' => array_slice( $values, 0, $max ), 'trimmed' => true, 'available' => $available ); } /** * Enforce a paragraph unit's hard word limit. * * On a non-final pass, over-limit text is flagged for a targeted retry * and left untouched. On the final pass, over-limit text is trimmed at * the last sentence boundary that still fits while keeping at least the * target minimum words and one full sentence; if no such boundary * exists, the text is kept as-is with a blocking finding. * * @param string[] $paragraphs Cleaned paragraphs. * @param array $length {targetMin,targetMax,hardMax}. * @param bool $final_pass Whether a targeted retry already happened (or none is possible). * @return array{paragraphs:string[],overLimit:bool,needsRetry:bool,findings:array} */ public function checkHardLimit( array $paragraphs, array $length, bool $final_pass ): array { $hard_max = $length['hardMax'] ?? null; if ( null === $hard_max ) { return array( 'paragraphs' => $paragraphs, 'overLimit' => false, 'needsRetry' => false, 'findings' => array() ); } $text = implode( ' ', $paragraphs ); $word_count = TextMetrics::wordCount( $text ); if ( $word_count <= (int) $hard_max ) { return array( 'paragraphs' => $paragraphs, 'overLimit' => false, 'needsRetry' => false, 'findings' => array() ); } if ( ! $final_pass ) { return array( 'paragraphs' => $paragraphs, 'overLimit' => true, 'needsRetry' => true, 'findings' => array() ); } $target_min = (int) ( $length['targetMin'] ?? 0 ); $sentences = TextMetrics::sentences( $text ); $total = count( $sentences ); for ( $keep = $total - 1; $keep >= 1; $keep-- ) { $candidate = implode( ' ', array_slice( $sentences, 0, $keep ) ); $candidate_words = TextMetrics::wordCount( $candidate ); if ( $candidate_words <= (int) $hard_max && $candidate_words >= $target_min ) { $removed = $total - $keep; return array( 'paragraphs' => array( $candidate ), 'overLimit' => false, 'needsRetry' => false, 'findings' => array( $this->finding( 'trimmed_at_sentence', 'warning', sprintf( /* translators: %d: number of sentences removed. */ _n( 'The text was shortened by %d sentence to fit the limit.', 'The text was shortened by %d sentences to fit the limit.', $removed, 'ai-product-tools' ), $removed ) ), ), ); } } return array( 'paragraphs' => $paragraphs, 'overLimit' => true, 'needsRetry' => false, 'findings' => array( $this->finding( 'hard_limit_exceeded', 'blocking', __( 'The text is still over its hard limit after a retry and could not be shortened without losing too much meaning.', 'ai-product-tools' ) ), ), ); } /** * Banned phrases present in $text (profile avoid list + blueprint-local * list, already merged by the caller), case-insensitive, matched on * Unicode word boundaries. * * @param string $text Plain text (already cleaned). * @param string[] $banned Banned phrases. * @return string[] The banned phrases actually found, in $banned's order. */ public function findBannedPhrases( string $text, array $banned ): array { $normalized = TextMetrics::normalizeForCompare( $text ); $found = array(); foreach ( $banned as $phrase ) { $needle = trim( (string) $phrase ); if ( '' === $needle ) { continue; } if ( $this->matchesWordBoundary( $normalized, $needle ) ) { $found[] = $needle; } } return $found; } /** * `NO_DATA_HEDGE_PHRASES` actually present in $text (same word-boundary * matching as {@see self::findBannedPhrases()}, against that fixed list * instead of the merchant's own banned-phrase one): `FaqGenerator` * retries a group once when this fires, then skips it instead of * keeping an answer that says it has no answer. * * @param string $text Plain text (already cleaned). * @return string[] The hedge phrases actually found. */ public function findNoDataHedgePhrases( string $text ): array { return $this->findBannedPhrases( $text, self::NO_DATA_HEDGE_PHRASES ); } /** * Preferred-term pairs whose "insteadOf" word appears in $text (measured * warning only, never retried). * * @param string $text Plain text (already cleaned). * @param array $preferred_terms {use,insteadOf} pairs. * @return array */ public function findPreferredTermHits( string $text, array $preferred_terms ): array { $normalized = TextMetrics::normalizeForCompare( $text ); $hits = array(); foreach ( $preferred_terms as $pair ) { $instead_of = trim( (string) ( $pair['insteadOf'] ?? '' ) ); if ( '' !== $instead_of && $this->matchesWordBoundary( $normalized, $instead_of ) ) { $hits[] = $pair; } } return $hits; } /** * Numeric tokens in $text whose bare digits never appeared anywhere in * the context the model was given (labelled heuristic). * * Compared on each token's numeric core only (its attached unit suffix, * if any, stripped first): the model is free to reformat a sourced * number's unit ("8 hours" -> "8hr", "1080p" for a sourced "1080") - that * is a faithful paraphrase, not a new, invented number, so it must read * the same as its bare source token either way the attaching happened. * Still a labelled heuristic: only the leading digits are ever compared, * never a verified magnitude or unit. * * @param string $text Plain text (already cleaned). * @param string[] $available_tokens Numeric tokens present in the supplied context. * @return string[] */ public function findUnsupportedNumbers( string $text, array $available_tokens ): array { $generated = TextMetrics::numericTokens( $text ); $available = array_fill_keys( array_map( array( self::class, 'numericCore' ), $available_tokens ), true ); return array_values( array_filter( $generated, static function ( $token ) use ( $available ) { return ! isset( $available[ self::numericCore( $token ) ] ); } ) ); } /** * Build one Finding record. * * @param string $code Finding code. * @param string $severity 'info' | 'warning' | 'review' | 'blocking'. * @param string $message Human-readable message. * @param string|null $unit_id Unit id, when the finding is unit-scoped. * @param array $data Extra structured data, when useful. * @return array{code:string,severity:string,message:string,unitId?:string,data?:array} */ public function finding( string $code, string $severity, string $message, ?string $unit_id = null, array $data = array() ): array { $finding = array( 'code' => $code, 'severity' => $severity, 'message' => $message ); if ( null !== $unit_id ) { $finding['unitId'] = $unit_id; } if ( ! empty( $data ) ) { $finding['data'] = $data; } return $finding; } /** * @param mixed $value Raw field value. * @param bool &$had_html Set true if tags were found in $value. * @return string */ private function cleanField( $value, bool &$had_html ): string { $value = is_string( $value ) ? $value : ''; if ( 1 === preg_match( '/<[a-zA-Z!\/][^>]*>/', $value ) ) { $had_html = true; } $value = (string) preg_replace( '/[\x00-\x08\x0B\x0C\x0E-\x1F]/u', '', $value ); $value = wp_strip_all_tags( $value ); $value = html_entity_decode( $value, ENT_QUOTES, 'UTF-8' ); $value = wp_strip_all_tags( $value ); $value = $this->stripMarkdown( $value ); $value = str_replace( array( "\r\n", "\r" ), "\n", $value ); $value = (string) preg_replace( '/[ \t]+/u', ' ', $value ); $value = (string) preg_replace( '/\s*\n\s*/u', ' ', $value ); return trim( $value ); } /** * @param string $text Text that may contain Markdown emphasis/list/heading markers. * @return string */ private function stripMarkdown( string $text ): string { $text = (string) preg_replace( '/^\s{0,3}#{1,6}\s+/mu', '', $text ); $text = (string) preg_replace( '/^\s*(?:[-*+]|\d+[.)])\s+/mu', '', $text ); $text = (string) preg_replace( '/(\*\*|__)(.+?)\1/su', '$2', $text ); $text = (string) preg_replace( '/(? */ private function htmlFinding( bool $had_html ): array { return $had_html ? array( $this->finding( 'html_removed', 'info', __( 'HTML in the AI answer was removed.', 'ai-product-tools' ) ) ) : array(); } /** * @param string $normalized_haystack Already-normalized (lowercased, whitespace-collapsed) text. * @param string $needle Phrase to find (any case). * @return bool */ private function matchesWordBoundary( string $normalized_haystack, string $needle ): bool { $pattern = '/(?