purposePresets( $options );
$purpose = $this->resolvePurpose( $options, $presets );
$tone = $this->resolveOptionString( $options, 'tone', 'Professional' );
$language = $this->resolveOptionString( $options, 'language', 'English' );
$length = $this->resolveOptionString( $options, 'length', 'medium' );
$purpose_details = $this->getPurposeDetails( $purpose, $presets, $length );
$product_context_block = $this->buildProductContext( $term_context );
$has_product_context = ( '' !== trim( $product_context_block ) ) && false === strpos( $product_context_block, 'No sampled product context is available' );
$term_data_block = $this->buildTermDataBlock( $term_context );
$task_context_modifier = $has_product_context
? 'Use term metadata together with product context to produce an accurate description.'
: 'Product context is empty. Rely on taxonomy metadata and existing term signals only.';
$system_prompt = PromptFormatter::cleanOutboundPrompt( $this->buildSystemPrompt( $tone, $language, $purpose, $purpose_details['rules'], $purpose_details['length_description'] ) );
$user_prompt = PromptFormatter::cleanOutboundPrompt(
$term_data_block . "\n\n" .
"\n" . $product_context_block . "\n\n\n" .
"# Task\n" .
$purpose_details['task'] . "\n" .
$task_context_modifier
);
/**
* Filter the parts appended to the user prompt. The Premium build adds
* the merchant's additional instructions here.
*
* @since 2.8.0
* @param string[] $extra_parts Prompt parts (none by default).
* @param array $options Prompt options.
*/
$extra_parts = apply_filters( 'aipt_taxonomy_prompt_parts', array(), $options );
foreach ( is_array( $extra_parts ) ? $extra_parts : array() as $extra_part ) {
if ( is_string( $extra_part ) && '' !== trim( $extra_part ) ) {
$user_prompt .= "\n\n" . $extra_part;
}
}
return array(
'system' => $system_prompt,
'user' => $user_prompt,
);
}
private function buildSystemPrompt( string $tone, string $language, string $purpose, string $purpose_rules, string $length_description ): string {
return "# Identity
You are an expert e-commerce content writer specializing in product category descriptions for WooCommerce stores.
# Rules
- Output ONLY valid HTML using
,
, - , , tags
- NEVER use markdown (no **, no ##, no -, no *)
- NEVER invent products, prices, features, or claims not present in the provided context
- Use ONLY the information provided in and
- Match the specified tone: {$tone}
- Write in: {$language}
- Target length: {$length_description}
- Purpose: {$purpose}
- {$purpose_rules}
- Never use an em-dash (—). Use a period, comma, or colon instead. This applies to the literal character AND any HTML-encoded form (named entity —, double-encoded —; numeric — / —); reject or regenerate output containing any equivalent em-dash representation.
# Quality Gate
Before responding, verify:
1. Is the output valid HTML and free of markdown?
2. Does the result match the {$purpose} purpose?
3. Does the description avoid invented facts and unsupported claims?
4. Is the output within the requested length target?";
}
private function buildTermDataBlock( array $term_context ): string {
$term_name = $this->contextString( $term_context, 'term_name', 'Unknown Term' );
$taxonomy_label = $this->contextString( $term_context, 'taxonomy_label', $this->contextString( $term_context, 'taxonomy', 'product_cat' ) );
$breadcrumb = $this->contextString( $term_context, 'breadcrumb', 'N/A' );
$existing_description = $this->contextString( $term_context, 'existing_description', 'None' );
$child_terms = $this->contextArrayString( $term_context, 'child_terms', 'None' );
$product_count = isset( $term_context['product_count'] ) ? absint( $term_context['product_count'] ) : 0;
return "
Term: {$term_name}
Taxonomy: {$taxonomy_label}
Breadcrumb: {$breadcrumb}
Existing Description: {$existing_description}
Child Categories: {$child_terms}
Product Count: {$product_count}
";
}
private function buildProductContext( array $term_context ): string {
if ( empty( $term_context['product_summary'] ) || ! is_array( $term_context['product_summary'] ) ) {
return 'No sampled product context is available for this term.';
}
$product_summary = $term_context['product_summary'];
$lines = array();
if ( ! empty( $product_summary['names'] ) && is_array( $product_summary['names'] ) ) {
$lines[] = 'Sample Product Names: ' . implode( ', ', array_map( 'sanitize_text_field', array_slice( $product_summary['names'], 0, 15 ) ) );
}
if ( ! empty( $product_summary['descriptions'] ) && is_array( $product_summary['descriptions'] ) ) {
$description_samples = array();
foreach ( array_slice( $product_summary['descriptions'], 0, 5 ) as $description ) {
$description_samples[] = $this->trimWords( sanitize_text_field( wp_strip_all_tags( (string) $description ) ), 30 );
}
if ( ! empty( $description_samples ) ) {
$lines[] = 'Product Description Signals: ' . implode( ' | ', $description_samples );
}
}
if ( ! empty( $product_summary['price_range'] ) && is_array( $product_summary['price_range'] ) ) {
$min = $product_summary['price_range']['min'] ?? null;
$max = $product_summary['price_range']['max'] ?? null;
if ( null !== $min && null !== $max ) {
$lines[] = sprintf( 'Observed Price Range: %s - %s', (string) $min, (string) $max );
} elseif ( null !== $max ) {
$lines[] = sprintf( 'Observed Price Range: Up to %s', (string) $max );
} elseif ( null !== $min ) {
$lines[] = sprintf( 'Observed Price Range: From %s', (string) $min );
}
}
if ( ! empty( $product_summary['attributes'] ) && is_array( $product_summary['attributes'] ) ) {
$lines[] = 'Attribute Summary: ' . implode( '; ', array_map( 'sanitize_text_field', array_slice( $product_summary['attributes'], 0, 20 ) ) );
}
if ( empty( $lines ) ) {
return 'No sampled product context is available for this term.';
}
return implode( "\n", $lines );
}
/**
* Purpose presets: the built-in ones plus any a registrant adds on
* `aipt_taxonomy_purpose_presets` (the Premium build adds `custom`). A
* registrant may add a preset, never replace a built-in one.
*
* @param array $options Prompt options.
* @return array
*/
private function purposePresets( array $options ): array {
$presets = array(
'seo_description' => array(
'rules' => 'Prioritize discoverability with natural keyword integration and clear search intent coverage.',
'task' => 'Generate an SEO-focused taxonomy description that targets likely category keywords and search intent.',
),
'marketing_overview' => array(
'rules' => 'Emphasize customer benefits, emotional value, and persuasive brand voice while staying factual.',
'task' => 'Generate a marketing overview for this taxonomy term with benefit-led messaging and compelling language.',
),
'technical_summary' => array(
'rules' => 'Focus on concrete specifications, product types, and objective facts without hype.',
'task' => 'Generate a technical summary that gives shoppers a clear, factual overview of what this category includes.',
),
'brand_story' => array(
'rules' => 'Use narrative style connected to brand values, lifestyle fit, and category purpose without inventing claims.',
'task' => 'Generate a brand story style description that frames this taxonomy term in a lifestyle and values context.',
),
);
/**
* Filter the taxonomy purpose presets.
*
* @since 2.8.0
* @param array $presets Purpose presets.
* @param array $options Prompt options.
*/
$filtered = apply_filters( 'aipt_taxonomy_purpose_presets', $presets, $options );
foreach ( is_array( $filtered ) ? $filtered : array() as $key => $preset ) {
if (
! is_string( $key )
|| sanitize_key( $key ) !== $key
|| isset( $presets[ $key ] )
|| ! is_array( $preset )
|| ! isset( $preset['rules'], $preset['task'] )
|| ! is_string( $preset['rules'] )
|| ! is_string( $preset['task'] )
) {
continue;
}
$presets[ $key ] = array(
'rules' => $preset['rules'],
'task' => $preset['task'],
);
}
return $presets;
}
/**
* @param string $purpose Resolved purpose.
* @param array $presets Purpose presets.
* @param string $length Requested length.
* @return array{rules:string,task:string,length_description:string}
*/
private function getPurposeDetails( string $purpose, array $presets, string $length ): array {
$length_description = $this->resolveLengthDescription( $length, $purpose );
if ( ! isset( $presets[ $purpose ] ) ) {
$purpose = 'seo_description';
}
$selected = $presets[ $purpose ];
if ( 'seo_description' === $purpose && '150-300 words' === $length_description ) {
$selected['task'] .= ' Keep the output between 150 and 300 words.';
}
return array(
'rules' => $selected['rules'],
'task' => $selected['task'],
'length_description' => $length_description,
);
}
private function resolvePurpose( array $options, array $presets ): string {
$purpose = $this->resolveOptionString( $options, 'purpose', 'seo_description' );
if ( ! isset( $presets[ $purpose ] ) ) {
return 'seo_description';
}
return $purpose;
}
private function resolveLengthDescription( string $length, string $purpose ): string {
if ( 'seo_description' === $purpose && ( 'medium' === $length || '' === $length ) ) {
return '150-300 words';
}
$map = array(
'short' => '80-140 words',
'medium' => '150-300 words',
'long' => '300-450 words',
);
return $map[ $length ] ?? $length;
}
private function resolveOptionString( array $options, string $key, string $fallback ): string {
if ( ! isset( $options[ $key ] ) || ! is_string( $options[ $key ] ) ) {
return $fallback;
}
$value = trim( wp_strip_all_tags( $options[ $key ] ) );
return '' === $value ? $fallback : $value;
}
private function contextString( array $context, string $key, string $fallback ): string {
if ( ! isset( $context[ $key ] ) ) {
return $fallback;
}
$value = is_scalar( $context[ $key ] ) ? (string) $context[ $key ] : '';
$value = trim( wp_strip_all_tags( $value ) );
return '' === $value ? $fallback : $value;
}
private function contextArrayString( array $context, string $key, string $fallback ): string {
if ( empty( $context[ $key ] ) || ! is_array( $context[ $key ] ) ) {
return $fallback;
}
$values = array_map(
static function ( $item ): string {
if ( ! is_scalar( $item ) ) {
return '';
}
return trim( wp_strip_all_tags( (string) $item ) );
},
$context[ $key ]
);
$values = array_values( array_filter( $values ) );
if ( empty( $values ) ) {
return $fallback;
}
return implode( ', ', $values );
}
private function trimWords( string $text, int $word_limit ): string {
$clean_text = trim( preg_replace( '/\s+/', ' ', $text ) ?? '' );
if ( '' === $clean_text ) {
return '';
}
$words = explode( ' ', $clean_text );
if ( count( $words ) <= $word_limit ) {
return $clean_text;
}
return implode( ' ', array_slice( $words, 0, $word_limit ) ) . '...';
}
}