'term:common_attributes', 'product_descriptions' => 'term:product_descriptions', ); /** * Clamp a Category descriptions definition: the custom section, the sample size, and a report for a paid term field a section picked. * * @param array &$definition Clamped definition (mutated in place). * @param array &$applied Accumulated appliedFreeDefaults entries. * @return void */ public function clamp( array &$definition, array &$applied ): void { $this->clampTaxonomyCustomSections( $definition, $applied ); $this->clampTaxonomySampleProducts( $definition, $applied ); $this->reportTaxonomyPaidSourceChoice( $definition, $applied ); } /** * Whether this site may use a Blueprint 'custom' AI section for * taxonomy (the structural equivalent of the legacy `purpose: 'custom'`). * Reads the exact filter `TaxonomyGeneratorService::applyPremiumControls()` * applies (`aipt_taxonomy_allowed_purposes`, default * `FREE_TAXONOMY_PURPOSES`), registered by * `Premium\TaxonomyGenerator\PremiumTaxonomyService::extend_allowed_purposes()`. * * @return bool */ public function taxonomyCustomPurposeAllowed(): bool { $allowed = apply_filters( 'aipt_taxonomy_allowed_purposes', self::FREE_TAXONOMY_PURPOSES ); return in_array( 'custom', is_array( $allowed ) ? $allowed : self::FREE_TAXONOMY_PURPOSES, true ); } /** * Taxonomy data sources this site may use. Reads the exact filter * `TaxonomyGeneratorService::applyPremiumControls()` applies * (`aipt_taxonomy_allowed_sources`, default `FREE_TAXONOMY_SOURCES`). * Used by `Context\TermContextBuilder` to decide whether `term: * common_attributes` and `term:product_descriptions` (the Blueprint * equivalents of the paid `product_attributes` and * `product_descriptions` sources) may be resolved. * * @return string[] */ public function taxonomyAllowedSources(): array { $allowed = apply_filters( 'aipt_taxonomy_allowed_sources', self::FREE_TAXONOMY_SOURCES ); return is_array( $allowed ) ? $allowed : self::FREE_TAXONOMY_SOURCES; } /** * Most sampled products a taxonomy term run may draw facts from. Reads * the exact filter `TaxonomyGeneratorService::applyPremiumControls()` * applies (`aipt_taxonomy_max_samples`, default `FREE_TAXONOMY_MAX_SAMPLES`). * Used by `Context\TermContextBuilder` to cap `term:top_products`, * `term:common_attributes` and `term:product_descriptions`, and handed * to the Blueprint editor so its sample-count control stops at the same * number. * * @return int */ public function taxonomyMaxSamples(): int { $max = apply_filters( 'aipt_taxonomy_max_samples', self::FREE_TAXONOMY_MAX_SAMPLES ); return ( is_int( $max ) && $max >= 1 ) ? $max : self::FREE_TAXONOMY_MAX_SAMPLES; } /** * Whether `term:common_attributes` may reach a taxonomy run, the * Blueprint equivalent of the paid `product_attributes` source * ({@see taxonomyAllowedSources()}). Public so the Blueprint editor says * which plan reads it. * * @return bool */ public function taxonomyCommonAttributesAllowed(): bool { return in_array( 'product_attributes', $this->taxonomyAllowedSources(), true ); } /** * Whether `term:product_descriptions` may reach a taxonomy run, the * Blueprint equivalent of the paid `product_descriptions` source * ({@see taxonomyAllowedSources()}). Public so the Blueprint editor says * which plan reads it. * * @return bool */ public function taxonomyProductDescriptionsAllowed(): bool { return in_array( 'product_descriptions', $this->taxonomyAllowedSources(), true ); } /** * The paid term fields this site withholds from a taxonomy run. * * @return string[] */ public function withheldTermRefs(): array { $allowed = $this->taxonomyAllowedSources(); $refs = array(); foreach ( self::TERM_PAID_SOURCE_REFS as $source => $ref ) { if ( ! in_array( $source, $allowed, true ) ) { $refs[] = $ref; } } return $refs; } /** * Report a section that picks a paid term field itself, as a data field * or as its condition, on a site that withholds it. * `Context\TermContextBuilder` does the withholding for every run, * which asks for those fields on its own; only a merchant's pick is * worth an entry, or one would follow every Free run. * * @param array $definition Clamped definition. * @param array &$applied Accumulated appliedFreeDefaults entries. * @return void */ private function reportTaxonomyPaidSourceChoice( array $definition, array &$applied ): void { $withheld = $this->withheldTermRefs(); if ( empty( $withheld ) || ! is_array( $definition['structure']['sections'] ?? null ) ) { return; } $picked = array(); foreach ( $definition['structure']['sections'] as $section ) { if ( ! is_array( $section ) || empty( $section['enabled'] ) ) { continue; } $keys = ( 'data' === ( $section['mode'] ?? '' ) && 'selected' === ( $section['fields']['mode'] ?? '' ) ) ? (array) ( $section['fields']['keys'] ?? array() ) : array(); $condition = ! empty( $section['condition']['enabled'] ) ? (string) ( $section['condition']['field'] ?? '' ) : ''; foreach ( $withheld as $ref ) { if ( in_array( $ref, $keys, true ) || $ref === $condition ) { $picked[ $ref ] = true; } } } if ( empty( $picked ) ) { return; } $applied[] = $this->freeDefault( 'taxonomy:sources', 'taxonomyPremiumSources', $this->taxonomySourcesMessage( array_keys( $picked ) ), __( 'more category data sources', 'ai-product-tools' ) ); } /** * @param string[] $picked Withheld term fields a section picked. * @return string */ private function taxonomySourcesMessage( array $picked ): string { $attributes = in_array( self::TERM_PAID_SOURCE_REFS['product_attributes'], $picked, true ); $descriptions = in_array( self::TERM_PAID_SOURCE_REFS['product_descriptions'], $picked, true ); if ( $attributes && $descriptions ) { return __( 'Common product attributes and product descriptions for this category were not sent to the AI in this run.', 'ai-product-tools' ); } if ( $descriptions ) { return __( 'Product descriptions for this category were not sent to the AI in this run.', 'ai-product-tools' ); } return __( 'Common product attributes for this category were not sent to the AI in this run.', 'ai-product-tools' ); } /** * Clamp a per-blueprint "Sample products per category" value * (`structure.sampleProducts`, schema-bounded 5..20, mirroring the * legacy slider) down to {@see taxonomyMaxSamples()} when the stored * value exceeds this site's entitlement. Unlike the common attributes * `Context\TermContextBuilder` withholds (data that never lives in the * definition), this value IS part of the definition, so it is clamped * here like every other definition-level field. * * @param array &$definition Clamped definition (mutated in place). * @param array &$applied Accumulated appliedFreeDefaults entries. * @return void */ private function clampTaxonomySampleProducts( array &$definition, array &$applied ): void { $requested = isset( $definition['structure']['sampleProducts'] ) ? (int) $definition['structure']['sampleProducts'] : 10; $max = $this->taxonomyMaxSamples(); if ( $requested <= $max ) { return; } $definition['structure']['sampleProducts'] = $max; $applied[] = $this->freeDefault( 'taxonomy:sampleProducts', 'taxonomyPremiumSources', __( 'This template asked to sample more products per category, so the standard sample was used instead.', 'ai-product-tools' ), __( 'a larger product sample', 'ai-product-tools' ) ); } /** * Disable every enabled, AI-mode 'custom' section when this site may * not use the legacy-equivalent `purpose: 'custom'`. A 'custom' section * in `fixed` or `data` mode is not this capability (it never turns a * free-text instruction into the task framing) and is left untouched, * matching the post-hoc check this replaces * (`TaxonomyGeneratorService::usesCustomPurposeEquivalent()`, which * only ever matched `mode === 'ai'`). * * Disabling here (BEFORE `SectionPlanner::plan()` runs) is what makes * the skip free: a disabled section needs no model call at all, so a * non-entitled attempt never spends one. * * @param array &$definition Clamped definition (mutated in place). * @param array &$applied Accumulated appliedFreeDefaults entries. * @return void */ private function clampTaxonomyCustomSections( array &$definition, array &$applied ): void { if ( $this->taxonomyCustomPurposeAllowed() ) { return; } if ( ! isset( $definition['structure']['sections'] ) || ! is_array( $definition['structure']['sections'] ) ) { return; } $dropped = false; foreach ( $definition['structure']['sections'] as $i => $section ) { if ( is_array( $section ) && 'custom' === ( $section['type'] ?? '' ) && 'ai' === ( $section['mode'] ?? '' ) && ! empty( $section['enabled'] ) ) { $definition['structure']['sections'][ $i ]['enabled'] = false; $dropped = true; } } if ( $dropped ) { $applied[] = $this->freeDefault( 'taxonomy:customSection', 'taxonomyPremiumPurpose', __( 'A custom-instruction section was skipped. Use a built-in section type instead.', 'ai-product-tools' ), __( 'custom-instruction sections', 'ai-product-tools' ) ); } } }