plan every section * (SectionPlanner, via Support\SubjectContextResolver) -> compile one * structured call for every pending AI unit (PromptCompiler, via * Support\PromptSpecBuilder) -> call the model, with the caller's own * bounded whole-answer repair retry, then at most one targeted retry for * units that are missing, invalid, over their hard limit, or still contain * a banned phrase (Support\GenerationRoundRunner) -> deterministic render, * strictly in definition order, measured checks, injected conflict * detection and eligibility (Support\ResultAssembler). * * This class itself only wires those four collaborators together; each * owns one stage of the pipeline and is independently unit-tested. * * @package AIPT\Api\ContentStructure\Engine\Generators * @since 2.8.0 */ namespace AIPT\Api\ContentStructure\Engine\Generators; use AIPT\Api\ContentStructure\Engine\Context\SourceContextBuilder; use AIPT\Api\ContentStructure\Engine\Generators\Support\GenerationRoundRunner; use AIPT\Api\ContentStructure\Engine\Generators\Support\PromptSpecBuilder; use AIPT\Api\ContentStructure\Engine\Generators\Support\ResultAssembler; use AIPT\Api\ContentStructure\Engine\Generators\Support\SubjectContextResolver; use AIPT\Api\ContentStructure\Engine\StructuredCallerInterface; use AIPT\Core\ContentStructure\Domain\Generators; use AIPT\Core\ContentStructure\Domain\SectionCatalog; defined( 'ABSPATH' ) || exit; /** * Description/taxonomy section pipeline orchestrator. */ class SectionGenerator implements GeneratorInterface { /** * @var SubjectContextResolver */ private $contextResolver; /** * @var PromptSpecBuilder */ private $specBuilder; /** * @var GenerationRoundRunner */ private $roundRunner; /** * @var ResultAssembler */ private $resultAssembler; /** * @var SourceContextBuilder */ private $sourceContextBuilder; public function __construct() { $this->contextResolver = new SubjectContextResolver(); $this->specBuilder = new PromptSpecBuilder(); $this->roundRunner = new GenerationRoundRunner(); $this->resultAssembler = new ResultAssembler(); $this->sourceContextBuilder = new SourceContextBuilder(); } /** * @inheritDoc */ public function generate( array $ctx, StructuredCallerInterface $caller ): array { $definition = $ctx['definition']; $all_sections = $this->sectionsOf( $definition ); $want_sections = $this->wantsSections( $ctx ); $sections = $want_sections ? $all_sections : array(); $subject_ctx = $this->contextResolver->buildSubjectContext( $ctx ); $blueprint_items = $definition['sources']['items'] ?? array(); $source_result = $this->sourceContextBuilder->build( $blueprint_items, $ctx['sources'] ?? array() ); $plans = $this->contextResolver->planSections( $sections, $subject_ctx, $source_result, $blueprint_items ); $pending_specs = $this->specBuilder->pendingUnitSpecs( $sections, $plans, $blueprint_items ); list( $normal_specs, $isolated_specs_by_type ) = $this->partitionIsolatedSpecs( $pending_specs ); $companions = $this->specBuilder->companionSpecs( $ctx, $definition ); $banned = $this->specBuilder->mergedBanned( $ctx, $definition ); $voice = $this->specBuilder->compileVoice( $ctx, $sections ); $usage = $this->emptyUsage(); $findings = $want_sections ? $this->noSectionsFinding( $all_sections ) : array(); if ( ! empty( $normal_specs ) || null !== $companions['short'] || null !== $companions['tags'] ) { $this->roundRunner->run( $caller, $ctx, $subject_ctx, $source_result, $normal_specs, $companions, $voice, $banned, $definition, $plans, $usage, $findings ); } foreach ( $isolated_specs_by_type as $type => $type_specs ) { $isolated_ctx = $this->contextResolver->buildIsolatedSubjectContext( $type, $ctx ); $isolated_source = array( 'blocks' => array(), 'sourcesUsed' => array() ); $no_companions = array( 'short' => null, 'tags' => null ); $this->roundRunner->run( $caller, $ctx, $isolated_ctx, $isolated_source, $type_specs, $no_companions, $voice, $banned, $definition, $plans, $usage, $findings, true ); } return $this->resultAssembler->assemble( $ctx, $sections, $plans, $subject_ctx, $definition, $source_result, $banned, $voice, $usage, $findings ); } /** * @inheritDoc */ public function regenerateUnit( array $ctx, array $previous, string $unit_id, StructuredCallerInterface $caller ): array { $definition = $ctx['definition']; $sections = $this->sectionsOf( $definition ); $section = $this->findSection( $sections, $unit_id ); if ( null === $section || 'ai' !== ( $section['mode'] ?? '' ) ) { return $previous; } $subject_ctx = $this->contextResolver->buildSubjectContext( $ctx ); $blueprint_items = $definition['sources']['items'] ?? array(); $source_result = $this->sourceContextBuilder->build( $blueprint_items, $ctx['sources'] ?? array() ); $plans = $this->contextResolver->planSections( $sections, $subject_ctx, $source_result, $blueprint_items ); if ( 'pending' !== $plans[ $unit_id ]['status'] ) { return $previous; } $pending_specs = array( $unit_id => $this->specBuilder->unitSpecFor( $section, $blueprint_items ) ); $banned = $this->specBuilder->mergedBanned( $ctx, $definition ); $voice = $this->specBuilder->compileVoice( $ctx, $sections ); $no_companions = array( 'short' => null, 'tags' => null ); $usage = $this->emptyUsage(); $findings = array(); $type = (string) ( $section['type'] ?? '' ); if ( SectionCatalog::isIsolatedUnit( $type ) ) { $isolated_ctx = $this->contextResolver->buildIsolatedSubjectContext( $type, $ctx ); $isolated_source = array( 'blocks' => array(), 'sourcesUsed' => array() ); $this->roundRunner->run( $caller, $ctx, $isolated_ctx, $isolated_source, $pending_specs, $no_companions, $voice, $banned, $definition, $plans, $usage, $findings, true ); } else { $this->roundRunner->run( $caller, $ctx, $subject_ctx, $source_result, $pending_specs, $no_companions, $voice, $banned, $definition, $plans, $usage, $findings ); } $plans[ $unit_id ]['regenerated'] = true; return $this->resultAssembler->assemble( $ctx, $sections, $plans, $subject_ctx, $definition, $source_result, $banned, $voice, $usage, $findings, $previous ); } /** * Split pending AI unit specs into the normal batch and one group per * distinct isolated TYPE present (SectionCatalog::isIsolatedUnit()). * Duplicates of the same isolated type share that type's one group * (and so its one extra call), since they share one type-specific * synthetic context; order follows each group's first appearance in * $pending_specs (definition order). * * @param array $pending_specs PromptSpecBuilder::pendingUnitSpecs()'s result. * @return array{0: array, 1: array>} [normal specs by id, isolated specs by type then id]. */ private function partitionIsolatedSpecs( array $pending_specs ): array { $normal = array(); $isolated = array(); foreach ( $pending_specs as $id => $spec ) { $type = (string) ( $spec['type'] ?? '' ); if ( SectionCatalog::isIsolatedUnit( $type ) ) { $isolated[ $type ][ $id ] = $spec; } else { $normal[ $id ] = $spec; } } return array( $normal, $isolated ); } /** * Whether this run should compile the structure's own sections at all. * Always true outside the description generator (taxonomy has no such * run option, and no caller sends one for it). For description, * `runOptions.wantSections` false means a caller that only wants this * run's companions - a tags-only or short-description-only * regeneration, say - so the long description's own AI/data units are * never compiled, and the provider is never asked for content nothing * will use. * * @param array $ctx Execution context. * @return bool */ private function wantsSections( array $ctx ): bool { if ( Generators::DESCRIPTION !== ( $ctx['generator'] ?? '' ) ) { return true; } return ! empty( $ctx['runOptions']['wantSections'] ?? true ); } /** * A structure with no configured sections at all produces an empty * description/category-description with nothing elsewhere in the * response to explain why - unless this run deliberately asked for no * sections at all (@see wantsSections()), which is by design and gets * no finding. The non-empty, non-"companion_"-prefixed unitId routes * this through ContentGenerator::blueprintTypeErrorMessage()'s existing * "any other unit's finding belongs to the description field" branch, * the same path every other Blueprint error already reaches the * merchant through. * * @param array[] $all_sections This structure's own BlueprintSection list, before any per-run filtering. * @return array[] Zero or one finding. */ private function noSectionsFinding( array $all_sections ): array { if ( ! empty( $all_sections ) ) { return array(); } return array( array( 'code' => 'no_sections_configured', 'severity' => 'warning', 'unitId' => 'description', 'message' => __( 'This template has no sections, so nothing was generated. Add one under 1 Content template.', 'ai-product-tools' ), ), ); } /** * @param array $definition Normalized BlueprintDefinition. * @return array[] BlueprintSection list. */ private function sectionsOf( array $definition ): array { return isset( $definition['structure']['sections'] ) && is_array( $definition['structure']['sections'] ) ? $definition['structure']['sections'] : array(); } /** * @param array[] $sections Sections. * @param string $id Section id. * @return array|null */ private function findSection( array $sections, string $id ): ?array { foreach ( $sections as $section ) { if ( ( $section['id'] ?? '' ) === $id ) { return $section; } } return null; } /** * @return array{aiCalls:int,nativeStructuredOutput:bool,provider:string,model:string,durationMs:int} */ private function emptyUsage(): array { return array( 'aiCalls' => 0, 'nativeStructuredOutput' => false, 'provider' => '', 'model' => '', 'durationMs' => 0 ); } }