compile ONE structured call for every pending group's * `count` question/answer pairs -> one bounded targeted retry for * missing/invalid/over-hard-limit/banned groups -> per-answer hard word * limit (retry, then sentence-trim, else that group needs review) -> drop * cross-group duplicate questions (keep the first) -> enforce the * blueprint-wide `maxQuestions` cap by trimming LATER groups' questions * first -> measured checks -> eligibility. The output stays a flat * `[{question, answer}]` array in group order: FAQ storage, schema markup * and display settings never know about "groups". * * @package AIPT\Api\ContentStructure\Engine\Generators * @since 2.8.0 */ namespace AIPT\Api\ContentStructure\Engine\Generators; use AIPT\Api\ContentStructure\Engine\Checks; use AIPT\Api\ContentStructure\Engine\Context\ProductContextBuilder; use AIPT\Api\ContentStructure\Engine\Context\SourceContextBuilder; use AIPT\Api\ContentStructure\Engine\DescriptiveFieldCheck; use AIPT\Api\ContentStructure\Engine\Generators\Formula\FaqAssembly; use AIPT\Api\ContentStructure\Engine\Generators\Formula\FormulaCallRunner; use AIPT\Api\ContentStructure\Engine\Generators\Formula\FormulaChecks; use AIPT\Api\ContentStructure\Engine\Generators\Formula\FormulaText; use AIPT\Api\ContentStructure\Engine\Generators\Support\PromptSpecBuilder; use AIPT\Api\ContentStructure\Engine\Generators\Support\SubjectContextResolver; use AIPT\Api\ContentStructure\Engine\LanguageResolver; use AIPT\Api\ContentStructure\Engine\OutputValidator; use AIPT\Api\ContentStructure\Engine\ProviderFailureSupport; use AIPT\Api\ContentStructure\Engine\SectionPlanner; use AIPT\Api\ContentStructure\Engine\StructureInstructions; use AIPT\Api\ContentStructure\Engine\StructuredCallerInterface; use AIPT\Api\ContentStructure\Engine\TextMetrics; use AIPT\Core\ContentStructure\Domain\FieldCatalog; defined( 'ABSPATH' ) || exit; /** * FAQ formula pipeline orchestrator. */ class FaqGenerator implements GeneratorInterface { /** * Filter registering content modes beyond 'both': receives * array * keyed by FaqStructure.mode (see modeOf()). */ public const MODES_FILTER = 'aipt_content_structure_faq_modes'; /** * @var OutputValidator */ private $validator; /** * @var SectionPlanner */ private $planner; /** * @var FormulaCallRunner */ private $callRunner; /** * @var PromptSpecBuilder */ private $specBuilder; /** * @var SourceContextBuilder */ private $sourceContextBuilder; /** * @var SubjectContextResolver */ private $subjectContextResolver; /** * A FaqGroup has no type, so a group that asks about warranty, care or * compatibility is recognised by its built-in id or by the words of its * topic and name (English and Turkish). */ private const TOPIC_GROUP_IDS = array( 'grp_warranty' => 'warranty', 'grp_care' => 'care', 'grp_compat' => 'compat', ); private const TOPIC_PATTERNS = array( 'warranty' => '/\b(warrant(y|ies)|guarantee[sd]?)\b|garanti/iu', 'care' => '/\b(care|caring|cleaning|washing|maintenance)\b|bakım|temizl|yıka/iu', 'compat' => '/\b(compatib(le|ility)|works with)\b|uyumlu/iu', ); public function __construct() { $this->validator = new OutputValidator(); $this->planner = new SectionPlanner(); $this->callRunner = new FormulaCallRunner(); $this->specBuilder = new PromptSpecBuilder(); $this->sourceContextBuilder = new SourceContextBuilder(); $this->subjectContextResolver = new SubjectContextResolver(); } /** * @inheritDoc */ public function generate( array $ctx, StructuredCallerInterface $caller ): array { return $this->run( $ctx, $caller, null, null ); } /** * @inheritDoc */ public function regenerateUnit( array $ctx, array $previous, string $unit_id, StructuredCallerInterface $caller ): array { $groups = $this->groupsOf( $ctx['definition'] ); $group = $this->findGroup( $groups, $unit_id ); if ( null === $group || empty( $group['enabled'] ) ) { return $previous; } return $this->run( $ctx, $caller, $unit_id, $previous ); } /** * @param array $ctx Execution context. * @param StructuredCallerInterface $caller Structured AI caller. * @param string|null $only_unit_id Set only when regenerating one group. * @param array|null $previous regenerateUnit()'s previous slice. * @return array{units:array,outputs:array,checks:array,conflicts:array,findings:array,sourcesUsed:array,eligibility:array,usage:array,providerError:array|null} */ private function run( array $ctx, StructuredCallerInterface $caller, ?string $only_unit_id, ?array $previous ): array { $definition = $ctx['definition']; $structure = $definition['structure']; $groups = $this->groupsOf( $definition ); $max_questions = (int) ( $structure['maxQuestions'] ?? 8 ); $mode = $this->modeOf( $structure ); $blueprint_items = $definition['sources']['items'] ?? array(); $fields = new FieldCatalog(); $product = $ctx['product']; $allowed_fields = isset( $definition['sources']['productFields'] ) ? array_values( (array) $definition['sources']['productFields'] ) : array(); $product_context = ( new ProductContextBuilder( $fields ) )->build( $product, $allowed_fields ); $source_result = $this->sourceContextBuilder->build( $blueprint_items, $ctx['sources'] ?? array() ); $usage = $this->callRunner->emptyUsage(); $findings = array(); $banned = $this->specBuilder->mergedBanned( $ctx, $definition ); list( $plans, $pending ) = $this->planGroups( $groups, $product_context, $source_result, $blueprint_items, $only_unit_id, $previous ); if ( ! empty( $pending ) ) { $this->runAiRound( $caller, $ctx, $definition, $product_context, $source_result, $blueprint_items, $pending, $banned, $mode, $plans, $usage, $findings ); } $exclude_questions = (array) ( $ctx['runOptions']['excludeQuestions'] ?? array() ); FaqAssembly::dropCrossGroupDuplicateQuestions( $groups, $plans, $findings, $exclude_questions ); FaqAssembly::enforceMaxQuestions( $groups, $plans, $max_questions, $findings ); return $this->assemble( $groups, $plans, $max_questions, $banned, $usage, $findings, $only_unit_id, $previous ); } /** * Decide every group's pre-call status: disabled, skipped by condition, * skipped for missing data, reused verbatim from a previous result * (every group except the one being regenerated), or pending an AI * call. * * @param array[] $groups FaqGroup list. * @param array $product_context ProductContextBuilder::build()'s result. * @param array $source_result SourceContextBuilder::build()'s result. * @param array $blueprint_items BlueprintSourcePolicy.items. * @param string|null $only_unit_id Set only when regenerating one group. * @param array|null $previous regenerateUnit()'s previous slice. * @return array{0:array,1:array} [plans by id, pending FaqGroup list by id]. */ private function planGroups( array $groups, array $product_context, array $source_result, array $blueprint_items, ?string $only_unit_id, ?array $previous ): array { $plans = array(); $pending = array(); foreach ( $groups as $group ) { $id = (string) $group['id']; if ( empty( $group['enabled'] ) ) { $plans[ $id ] = array( 'status' => 'disabled', 'reason' => __( 'This group is turned off.', 'ai-product-tools' ), 'pairs' => array() ); continue; } if ( ! empty( $group['condition']['enabled'] ) && ! $this->planner->evaluateCondition( $group['condition'], $product_context['fieldValues'] ) ) { $plans[ $id ] = array( 'status' => 'skipped_condition', 'reason' => $this->conditionReason( $group['condition'], $product_context ), 'pairs' => array() ); continue; } if ( null !== $only_unit_id && $id !== $only_unit_id && null !== $previous ) { $prev_unit = $this->findUnit( (array) $previous['units'], $id ); if ( null !== $prev_unit ) { $plans[ $id ] = array( 'status' => $prev_unit['status'], 'reason' => $prev_unit['reason'], 'pairs' => (array) $prev_unit['qa'] ); continue; } } if ( $this->isDataStarved( $group, $product_context, $source_result['blocks'], $blueprint_items ) ) { $plans[ $id ] = array( 'status' => 'skipped_missing_data', 'reason' => __( 'No usable data was found for this group, so the AI was not asked to write it.', 'ai-product-tools' ), 'pairs' => array() ); continue; } if ( $this->lacksTopicFact( $group, $product_context, $source_result['blocks'], $blueprint_items ) ) { $plans[ $id ] = array( 'status' => 'skipped_missing_data', 'reason' => __( 'The product data has no fact on this group\'s topic, so the AI was not asked to write it.', 'ai-product-tools' ), 'pairs' => array() ); continue; } $pending[ $id ] = $group; } return array( $plans, $pending ); } /** * Whether a warranty, care or compatibility group has no fact on its * topic in the product's fields or its sources' facts. * * @param array $group FaqGroup. * @param array $product_context ProductContextBuilder::build()'s result. * @param array $source_blocks SourceContextBuilder::build()'s `blocks`. * @param array $blueprint_items BlueprintSourcePolicy.items. * @return bool */ private function lacksTopicFact( array $group, array $product_context, array $source_blocks, array $blueprint_items ): bool { $topic = self::TOPIC_GROUP_IDS[ (string) $group['id'] ] ?? null; if ( null === $topic ) { $words = (string) ( $group['topic'] ?? '' ) . ' ' . (string) ( $group['name'] ?? '' ); foreach ( self::TOPIC_PATTERNS as $kind => $pattern ) { if ( 1 === preg_match( $pattern, $words ) ) { $topic = $kind; break; } } } if ( null === $topic ) { return false; } $refs = $this->sourceContextBuilder->refsForSection( $group['sources'], $blueprint_items ); $fact_labels = array(); foreach ( $this->sourceContextBuilder->usableBlocksForRefs( $source_blocks, $refs ) as $block ) { foreach ( (array) ( $block['facts'] ?? array() ) as $fact ) { $fact_labels[] = (string) ( $fact['label'] ?? '' ); } } return ! $this->subjectContextResolver->hasTopicFact( $product_context['fieldValues'], $fact_labels, $topic ); } /** * Generic data-starved signal (the default rule: "the * product name plus one allowed field"); a warranty, care or * compatibility group is checked for a fact on its topic separately * ({@see self::lacksTopicFact()}). * * @param array $group FaqGroup. * @param array $product_context ProductContextBuilder::build()'s result. * @param array $source_blocks SourceContextBuilder::build()'s `blocks`. * @param array $blueprint_items BlueprintSourcePolicy.items. * @return bool */ private function isDataStarved( array $group, array $product_context, array $source_blocks, array $blueprint_items ): bool { $refs = $this->sourceContextBuilder->refsForSection( $group['sources'], $blueprint_items ); $field_values = $product_context['fieldValues']; $name_value = $field_values['core:name'] ?? null; $has_name = null !== $name_value && empty( $name_value['empty'] ); $has_any_field = DescriptiveFieldCheck::hasAnyDescriptiveField( $field_values, 'core:name' ); if ( ! $has_any_field ) { foreach ( $this->sourceContextBuilder->usableBlocksForRefs( $source_blocks, $refs ) as $block ) { if ( '' !== trim( (string) $block['text'] ) ) { $has_any_field = true; break; } } } return ! $has_name || ! $has_any_field; } /** * @param array $condition {field,operator,value}. * @param array $product_context ProductContextBuilder::build()'s result. * @return string */ private function conditionReason( array $condition, array $product_context ): string { $ref = (string) ( $condition['field'] ?? '' ); $label = ( new FieldCatalog() )->label( $ref ); $label = '' !== $label ? $label : $ref; unset( $product_context ); switch ( (string) ( $condition['operator'] ?? '' ) ) { case 'not_empty': /* translators: %s: the condition's field label. */ return sprintf( __( 'Skipped because %s is empty for this subject.', 'ai-product-tools' ), $label ); case 'empty': /* translators: %s: the condition's field label. */ return sprintf( __( 'Skipped because %s is not empty for this subject.', 'ai-product-tools' ), $label ); default: /* translators: %s: the condition's field label. */ return sprintf( __( 'Skipped because the condition on %s was not met.', 'ai-product-tools' ), $label ); } } /** * Run the one shared structured call for every pending group's * question/answer pairs, with at most one targeted retry for groups * missing, invalid, over an answer's hard limit, or still containing a * banned phrase, then resolve every pending group's final pairs into * `$plans` (in place). * * @param StructuredCallerInterface $caller Structured AI caller. * @param array $ctx Execution context. * @param array $definition Normalized BlueprintDefinition. * @param array $product_context ProductContextBuilder::build()'s result. * @param array $source_result SourceContextBuilder::build()'s result. * @param array $blueprint_items BlueprintSourcePolicy.items. * @param array $pending Pending FaqGroup list, keyed by id. * @param string[] $banned Merged banned phrases. * @param array $mode modeOf()'s result. * @param array &$plans Plans-by-id accumulator, updated in place. * @param array &$usage Usage accumulator, updated in place. * @param array &$findings Findings accumulator, updated in place. * @return void */ private function runAiRound( StructuredCallerInterface $caller, array $ctx, array $definition, array $product_context, array $source_result, array $blueprint_items, array $pending, array $banned, array $mode, array &$plans, array &$usage, array &$findings ): void { $deadline = isset( $ctx['deadline'] ) ? (float) $ctx['deadline'] : ( microtime( true ) + 60.0 ); $budget = isset( $ctx['maxCalls'] ) ? max( 1, (int) $ctx['maxCalls'] ) : 3; $voice = $this->specBuilder->compileVoice( $ctx, array() ); $language = LanguageResolver::resolve( $ctx, $definition ); $ai_note = (string) ( $ctx['aiNote'] ?? '' ); $existing = (array) ( $ctx['runOptions']['excludeQuestions'] ?? array() ); $compiled = FaqAssembly::compileRequest( $pending, $product_context, $source_result, $blueprint_items, $language, $voice, $banned, $ai_note, array(), $mode, StructureInstructions::enabled( $definition ), $existing ); $first = $this->callRunner->call( $caller, $ctx, $compiled, min( 2, $budget ), $deadline ); $this->callRunner->mergeUsage( $usage, $first ); $calls_used = $first['calls']; $by_id = array(); if ( $first['ok'] ) { $match = $this->validator->matchUnits( $first['decoded']['groups'] ?? array(), array_keys( $pending ) ); $findings = array_merge( $findings, $match['findings'] ); $by_id = $match['byId']; } else { $findings = ProviderFailureSupport::recordTerminalFailure( $findings, (array) ( $first['error'] ?? array() ) ); } list( $cleaned, $retry_ids ) = $this->validateFirstPass( $pending, $by_id, $banned, $mode ); $retry_result = null; if ( ! empty( $retry_ids ) && $this->callRunner->canRetry( $budget, $calls_used, $deadline ) ) { $retry_pending = array_intersect_key( $pending, array_flip( $retry_ids ) ); $retry_notes = array_fill_keys( $retry_ids, __( 'missing, invalid, over an answer word limit, still used a banned phrase, or said the information is not provided (return an empty "questions" list for that group instead)', 'ai-product-tools' ) ); $retry_compiled = FaqAssembly::compileRequest( $retry_pending, $product_context, $source_result, $blueprint_items, $language, $voice, $banned, $ai_note, $retry_notes, $mode, StructureInstructions::enabled( $definition ), $existing ); $retry_result = $this->callRunner->call( $caller, $ctx, $retry_compiled, 1, $deadline, $first['provider'], $first['model'] ); $this->callRunner->mergeUsage( $usage, $retry_result ); if ( $retry_result['ok'] ) { $retry_match = $this->validator->matchUnits( $retry_result['decoded']['groups'] ?? array(), $retry_ids ); $findings = array_merge( $findings, $retry_match['findings'] ); foreach ( $retry_match['byId'] as $id => $raw ) { $by_id[ $id ] = $raw; } } else { $findings = ProviderFailureSupport::recordTerminalFailure( $findings, (array) ( $retry_result['error'] ?? array() ) ); } } $failure_messages = ProviderFailureSupport::unitFailureMessages( $first, array_keys( $pending ), $retry_result, $retry_ids ); foreach ( $pending as $id => $group ) { $plans[ $id ] = $this->resolveGroup( $id, $group, $by_id[ $id ] ?? null, $definition, $banned, $product_context, $source_result, $blueprint_items, $mode, $findings, $failure_messages[ $id ] ?? null ); } } /** * First validation pass (not final): shape-clean every pending group's * raw answer, collecting which groups need the one allowed targeted * retry (missing, invalid shape, an over-hard-limit answer, or a * banned phrase). Never trims/sentence-cuts here. * * @param array $pending Pending FaqGroup list, keyed by id. * @param array $by_id Matched raw payloads, keyed by id. * @param string[] $banned Merged banned phrases. * @param array $mode modeOf()'s result. * @return array{0:array,1:string[]} [cleaned pairs by id, retry ids]. */ private function validateFirstPass( array $pending, array $by_id, array $banned, array $mode ): array { $cleaned = array(); $retry_ids = array(); foreach ( $pending as $id => $group ) { $raw = $by_id[ $id ] ?? null; if ( null === $raw || ! isset( $raw['questions'] ) || ! is_array( $raw['questions'] ) ) { $retry_ids[] = $id; continue; } if ( $this->isNoDataAnswer( $raw, $mode ) ) { $cleaned[ $id ] = array(); continue; } $pairs = $this->cleanPairs( (array) $raw['questions'], $mode ); $cleaned[ $id ] = $pairs; if ( empty( $pairs ) ) { $retry_ids[] = $id; continue; } $needs_retry = false; foreach ( $pairs as $pair ) { $limit = $this->validator->checkHardLimit( array( $pair['answer'] ), array( 'targetMin' => 0, 'targetMax' => $group['answer']['targetMax'], 'hardMax' => $group['answer']['hardMax'] ), false ); if ( $limit['needsRetry'] ) { $needs_retry = true; break; } if ( ! empty( $this->validator->findBannedPhrases( $pair['question'] . ' ' . $pair['answer'], $banned ) ) ) { $needs_retry = true; break; } if ( ! empty( $this->validator->findNoDataHedgePhrases( $pair['answer'] ) ) ) { $needs_retry = true; break; } } if ( $needs_retry ) { $retry_ids[] = $id; } } return array( $cleaned, array_values( array_unique( $retry_ids ) ) ); } /** * Whether a group came back as an empty `questions` list in a mode that * writes answers: the model's way of saying the data does not cover the * topic (FaqAssembly::NO_DATA_RULE). A questions-only run is never told * to do that, so an empty list there stays a failure. * * @param array $raw Matched raw payload. * @param array $mode modeOf()'s result. * @return bool */ private function isNoDataAnswer( array $raw, array $mode ): bool { return ! empty( $mode['answer'] ) && isset( $raw['questions'] ) && array() === $raw['questions']; } /** * Whether any pair's answer still reads as * `OutputValidator::NO_DATA_HEDGE_PHRASES` (see {@see self::resolveGroup()}). * * @param array[] $pairs Cleaned `{question,answer}` pairs. * @return bool */ private function anyAnswerHedges( array $pairs ): bool { foreach ( $pairs as $pair ) { if ( ! empty( $this->validator->findNoDataHedgePhrases( (string) $pair['answer'] ) ) ) { return true; } } return false; } /** * Clean a group's raw `{question,answer}` pairs. A side the mode does not * write is forced blank regardless of what the model actually returned * (its instruction-following is never trusted over this): a blank * field, never a lookup against the product's already-stored FAQ * questions. * * @param array[] $raw_pairs Raw `{question,answer}` list. * @param array $mode modeOf()'s result. * @return array */ private function cleanPairs( array $raw_pairs, array $mode ): array { $pairs = array(); foreach ( $raw_pairs as $raw_pair ) { if ( ! is_array( $raw_pair ) ) { continue; } $question = empty( $mode['question'] ) ? array( 'ok' => true, 'text' => '' ) : FormulaText::cleanOne( $this->validator, (string) ( $raw_pair['question'] ?? '' ) ); $answer = empty( $mode['answer'] ) ? array( 'ok' => true, 'text' => '' ) : FormulaText::cleanOne( $this->validator, (string) ( $raw_pair['answer'] ?? '' ) ); if ( $question['ok'] && $answer['ok'] ) { $pairs[] = array( 'question' => $question['text'], 'answer' => $answer['text'] ); } } return $pairs; } /** * The structure's content mode. 'both' (question and answer, the default * and the mode of a structure saved before this field existed) is the * engine's own; any other mode comes from the * `aipt_content_structure_faq_modes` filter (the Business build * registers 'questions' and 'answers'), and a mode no one registered * runs as 'both'. * * @param array $structure Normalized FaqStructure. * @return array{system:string,user:string,question:bool,answer:bool} The mode's extra instruction, its per-group instruction ('' for the default) and which sides it writes. */ private function modeOf( array $structure ): array { $both = array( 'system' => '', 'user' => '', 'question' => true, 'answer' => true ); $key = (string) ( $structure['mode'] ?? 'both' ); if ( 'both' === $key ) { return $both; } $modes = apply_filters( self::MODES_FILTER, array() ); $mode = is_array( $modes ) && is_array( $modes[ $key ] ?? null ) ? $modes[ $key ] : array(); $spec = array( 'system' => is_string( $mode['system'] ?? null ) ? $mode['system'] : '', 'user' => is_string( $mode['user'] ?? null ) ? $mode['user'] : '', 'question' => ! empty( $mode['question'] ), 'answer' => ! empty( $mode['answer'] ), ); return ( $spec['question'] || $spec['answer'] ) && '' !== $spec['user'] ? $spec : $both; } /** * @param string $id Group id. * @param array $group FaqGroup. * @param array|null $raw Matched raw payload (post-retry), or null. * @param array $definition Normalized BlueprintDefinition. * @param string[] $banned Merged banned phrases. * @param array $product_context ProductContextBuilder::build()'s result. * @param array $source_result SourceContextBuilder::build()'s result. * @param array $blueprint_items BlueprintSourcePolicy.items. * @param array $mode modeOf()'s result. * @param array &$findings Findings accumulator, updated in place. * @param string|null $provider_message The classified provider message responsible for this group still being missing, when `$raw` is null because its own call failed; null otherwise (see ProviderFailureSupport::unitFailureMessages()). * @return array{status:string,reason:string,pairs:array} */ private function resolveGroup( string $id, array $group, ?array $raw, array $definition, array $banned, array $product_context, array $source_result, array $blueprint_items, array $mode, array &$findings, ?string $provider_message = null ): array { $no_data_reason = __( 'The product data has nothing that answers this topic, so the group was skipped.', 'ai-product-tools' ); if ( null !== $raw && $this->isNoDataAnswer( $raw, $mode ) ) { return array( 'status' => 'skipped_missing_data', 'reason' => $no_data_reason, 'pairs' => array() ); } $pairs = ( null !== $raw && isset( $raw['questions'] ) && is_array( $raw['questions'] ) ) ? $this->cleanPairs( (array) $raw['questions'], $mode ) : array(); if ( empty( $pairs ) ) { $message = ( null === $raw && null !== $provider_message ) ? $provider_message : __( 'The AI did not return this group.', 'ai-product-tools' ); $required_failure = (string) ( $definition['rules']['requiredFailure'] ?? 'review' ); if ( 'partial' === $required_failure ) { $findings[] = $this->validator->finding( 'unit_failed_dropped', 'warning', $message, $id ); return array( 'status' => 'skipped_missing_data', 'reason' => $message, 'pairs' => array() ); } $findings[] = $this->validator->finding( 'unit_failed', 'review', $message, $id ); return array( 'status' => 'needs_review', 'reason' => $message, 'pairs' => array() ); } if ( $this->anyAnswerHedges( $pairs ) ) { return array( 'status' => 'skipped_missing_data', 'reason' => $no_data_reason, 'pairs' => array() ); } $trim = $this->validator->trimToMax( $pairs, (int) $group['count'] ); $pairs = $trim['values']; if ( $trim['trimmed'] ) { /* translators: %1$d: configured question count. %2$d: number of questions the model actually returned. */ $findings[] = $this->validator->finding( 'items_trimmed', 'warning', sprintf( __( 'Kept the first %1$d of %2$d questions the model returned for this group.', 'ai-product-tools' ), (int) $group['count'], $trim['available'] ), $id ); } if ( count( $pairs ) < (int) $group['count'] ) { /* translators: %1$d: number of questions returned. %2$d: configured question count. */ $findings[] = $this->validator->finding( 'items_short', 'info', sprintf( __( 'This group has %1$d of the %2$d questions asked for: the product data supports fewer.', 'ai-product-tools' ), count( $pairs ), (int) $group['count'] ), $id ); } $over_limit = false; $final_pairs = array(); $numeric_tokens = array_merge( (array) $product_context['numericTokens'], $this->numericTokensFor( $this->sourceContextBuilder->refsForSection( $group['sources'], $blueprint_items ), $source_result['blocks'] ) ); foreach ( $pairs as $pair ) { $limit = $this->validator->checkHardLimit( array( $pair['answer'] ), array( 'targetMin' => 0, 'targetMax' => $group['answer']['targetMax'], 'hardMax' => $group['answer']['hardMax'] ), true ); $pair['answer'] = $limit['paragraphs'][0] ?? $pair['answer']; foreach ( $limit['findings'] as $finding ) { $finding['unitId'] = $id; $findings[] = $finding; } if ( $limit['overLimit'] ) { $over_limit = true; } $combined = $pair['question'] . ' ' . $pair['answer']; $still_banned = $this->validator->findBannedPhrases( $combined, $banned ); if ( ! empty( $still_banned ) ) { /* translators: %s: comma-separated banned phrases still present after the retry. */ $findings[] = $this->validator->finding( 'banned_phrase', 'review', sprintf( __( 'This group still uses a banned phrase: %s.', 'ai-product-tools' ), implode( ', ', $still_banned ) ), $id ); } $unsupported = $this->validator->findUnsupportedNumbers( $combined, $numeric_tokens ); if ( ! empty( $unsupported ) ) { /* translators: %s: comma-separated numeric tokens not found in the supplied context. */ $findings[] = $this->validator->finding( 'unsupported_number', 'warning', sprintf( __( 'This group mentions a number not found in the provided context: %s.', 'ai-product-tools' ), implode( ', ', $unsupported ) ), $id ); } $final_pairs[] = $pair; } if ( $over_limit ) { return array( 'status' => 'needs_review', 'reason' => __( 'One answer in this group is still over its hard word limit after a retry.', 'ai-product-tools' ), 'pairs' => $final_pairs ); } return array( 'status' => 'included', 'reason' => '', 'pairs' => $final_pairs ); } /** * @param string[] $refs A group's allowed source refs. * @param array $source_blocks SourceContextBuilder::build()'s `blocks`. * @return string[] */ private function numericTokensFor( array $refs, array $source_blocks ): array { $tokens = array(); foreach ( $this->sourceContextBuilder->usableBlocksForRefs( $source_blocks, $refs ) as $block ) { $tokens = array_merge( $tokens, TextMetrics::numericTokens( (string) $block['text'] ) ); } return $tokens; } /** * Build units/checks/findings and assemble the generator-specific * GenerationResult slice. * * @param array[] $groups FaqGroup list, in order. * @param array $plans Final plans-by-id. * @param int $max_questions Hard cap. * @param string[] $banned Merged banned phrases. * @param array $usage Usage accumulator. * @param array $findings Findings accumulated during generation. * @param string|null $only_unit_id Set only when regenerating one group. * @param array|null $previous regenerateUnit()'s previous slice, when regenerating. * @return array{units:array,outputs:array,checks:array,conflicts:array,findings:array,sourcesUsed:array,eligibility:array,usage:array,providerError:array|null} */ private function assemble( array $groups, array $plans, int $max_questions, array $banned, array $usage, array $findings, ?string $only_unit_id, ?array $previous = null ): array { $units = array(); $faq = array(); $all_text_parts = array(); foreach ( $groups as $group ) { $id = (string) $group['id']; $plan = $plans[ $id ]; $text = implode( ' ', array_map( static function ( $pair ) { return $pair['question'] . ' ' . $pair['answer']; }, $plan['pairs'] ) ); if ( in_array( $plan['status'], array( 'included', 'fallback' ), true ) ) { $all_text_parts[] = $text; } foreach ( $plan['pairs'] as $pair ) { $faq[] = $pair; } $units[] = array( 'id' => $id, 'kind' => 'group', 'type' => 'faq_group', 'name' => (string) $group['name'], 'mode' => 'ai', 'format' => 'paragraph', 'status' => $plan['status'], 'reason' => $plan['reason'], 'heading' => '', 'html' => '', 'text' => $text, 'items' => array(), 'rows' => array(), 'qa' => $plan['pairs'], 'wordCount' => TextMetrics::wordCount( $text ), 'charCount' => TextMetrics::charCount( $text ), 'itemCount' => count( $plan['pairs'] ), 'missingFields' => array(), 'usedFallback' => false, 'regenerated' => null !== $only_unit_id && $id === $only_unit_id, 'sourceRefs' => $this->sourceContextBuilder->refsForSection( $group['sources'], array() ), 'findings' => array(), ); } $checks = array(); foreach ( $units as $unit ) { if ( ! in_array( $unit['status'], array( 'included', 'fallback' ), true ) ) { $checks[] = ( new Checks() )->statusNote( $unit['id'], $unit['name'], $unit['status'], $unit['reason'] ); } } foreach ( $groups as $group ) { $id = (string) $group['id']; $plan = $plans[ $id ]; if ( ! in_array( $plan['status'], array( 'included', 'fallback' ), true ) || empty( $plan['pairs'] ) ) { continue; } $answer_word_counts = array_map( static function ( $pair ) { return TextMetrics::wordCount( (string) $pair['answer'] ); }, $plan['pairs'] ); $longest = max( $answer_word_counts ); $target = (int) $group['answer']['targetMax']; /* translators: %1$d: word count of the group's longest answer. %2$d: the group's answer word target. */ $detail = sprintf( __( 'Longest answer %1$d words - target up to %2$d.', 'ai-product-tools' ), $longest, $target ); if ( $longest > $target ) { $detail .= ' ' . __( 'Above target.', 'ai-product-tools' ); } $checks[] = FormulaChecks::row( 'word_target', (string) $group['name'], $longest > $target ? 'warn' : 'pass', $detail, $id ); } $short_count = count( array_filter( $findings, static function ( $f ) { return 'items_short' === ( $f['code'] ?? '' ); } ) ); $total_questions = count( $faq ); $checks[] = FormulaChecks::row( 'question_count', __( 'Question count', 'ai-product-tools' ), 'pass', 0 === $short_count /* translators: %1$d: total question count. %2$d: configured cap. */ ? sprintf( __( '%1$d questions - cap %2$d (enforced).', 'ai-product-tools' ), $total_questions, $max_questions ) /* translators: %1$d: total question count. %2$d: configured cap. %3$d: number of groups with fewer questions than configured. */ : sprintf( _n( '%1$d questions - cap %2$d (enforced). %3$d group has fewer questions than configured: the product data supports fewer.', '%1$d questions - cap %2$d (enforced). %3$d groups have fewer questions than configured: the product data supports fewer.', $short_count, 'ai-product-tools' ), $total_questions, $max_questions, $short_count ) ); $combined_text = implode( ' ', $all_text_parts ); $checker = new Checks(); $checks[] = $checker->bannedPhrases( $this->validator->findBannedPhrases( $combined_text, $banned ) ); $provider_error = ProviderFailureSupport::providerErrorFromFindings( $findings ); $provider_error = ProviderFailureSupport::carryForwardProviderError( $units, $provider_error, $previous ); $findings = ProviderFailureSupport::applyAiOutcomeRules( $units, $findings, $provider_error ); $eligibility = $checker->eligibility( $findings, array() ); return array( 'units' => $units, 'outputs' => array( 'faq' => $faq ), 'checks' => $checks, 'conflicts' => array(), 'findings' => $findings, 'sourcesUsed' => array(), 'eligibility' => $eligibility, 'usage' => $usage, 'providerError' => $provider_error, ); } /** * @param array $definition Normalized BlueprintDefinition. * @return array[] FaqGroup list. */ private function groupsOf( array $definition ): array { return isset( $definition['structure']['groups'] ) && is_array( $definition['structure']['groups'] ) ? $definition['structure']['groups'] : array(); } /** * @param array[] $groups FaqGroup list. * @param string $id Group id. * @return array|null */ private function findGroup( array $groups, string $id ): ?array { foreach ( $groups as $group ) { if ( ( $group['id'] ?? '' ) === $id ) { return $group; } } return null; } /** * @param array[] $units Rendered units. * @param string $id Unit id. * @return array|null */ private function findUnit( array $units, string $id ): ?array { foreach ( $units as $unit ) { if ( ( $unit['id'] ?? '' ) === $id ) { return $unit; } } return null; } }